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ABSTRACT 


This report describes the design and implementation of a Concurrent Image 
Processing Executive (CIPE), which is intended to become the support system 
software for a prototype high performance science analysis workstation. The 
target machine for this software is a JPL/Caltech Mark fflfp Hypercube hosted 
by either a MASSCOMP 5600 or a Sun-3, Sun-4 workstation; however, the 
design will accommodate other concurrent machines of similar architecture, i.e., 
local memory, multiple-instruction-multiple-data (MIMD) machines. The CIPE 
system provides both a multimode user interface and an applications program- 
mer interface, and has been designed around four loosely coupled modules: (1) 
user interface, (2) host-resident executive, (3) hypercube-resident executive, and 
(4) application functions. The loose coupling between modules allows 
modification of a particular module without significantly affecting the other 
modules in the system. In order to enhance hypercube memory utilization and 
to allow expansion of image processing capabilities, a specialized program 
management method, incremental loading, was devised. To minimize data 
transfer between host and hypercube, a data management method which distri- 
butes, redistributes, and tracks data set information was implemented. The data 
management also allows data sharing among application programs. The CIPE 
software architecture provides a flexible environment for scientific analysis of 
complex remote sensing image data, such as imaging spectrometry, utilizing 
state-of-the-art concurrent computation capabilities. 
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INTRODUCTION 


The current and projected growth in volume and complexity of the National 
Aeronautics and Space Administration (NASA) mission remote sensing image 
data is placing a considerable strain on the computational resources available to 
the science community for analyzing and interpreting this valuable source of 
information. By the end of this century, given the Earth Observing System 
(EOS) and other NASA space exploration missions, the wealth of data available 
to scientists in a variety of disciplines will be truly astounding. In order to 
address the problems associated with analyzing this data, a new generation of 
computational resources and tools must be developed and made available to the 
NASA science community. This task report describes work carried out during 
FY88 which addresses one aspect of this problem, i.e., the development of user 
environments and tools for high-performance science analysis workstations. 
This work has been carried out in the context of implementing a Concurrent 
Image Processing and Analysis Testbed (CIPAT), which will form a prototype 
high-performance workstation. The utilization of emerging concurrent process- 
ing technology, in particular multiple-instruction-multiple-data (MIMD) archi- 
tectures which provide large amounts of local memory, is a natural approach to 
handling compute-intensive problems with large data sets. This technology 
presents its own unique set of problems, however, particularly with respect to 
system software design and interactive user environments. The work described 
in this report provides one solution to these problems through the implementa- 
tion of a general executive software system, the Concurrent Image Processing 
Executive (CIPE). 

As the name implies, CIPE was designed for hardware systems which utilize 
concurrent computational resources for the processing of image and other mul- 
tidimensional data; more specifically, the concurrent computational resource is 
assumed to be an attached processor which is connected to a host computer. In 
this context, the host machine provides the usual broad range of operating sys- 
tem services, file I/O, display device hardware, network connections, etc. 
Although the executive described in this report could be extended to cover 
commercial multiprocessor computers such as Alliant, Convex, EIxsi, Flex, etc., 
that was not a design objective. The hardware environment within which CIPE 
was developed consists of a MASSCOMP 5600 dual-processor host machine, 
with approximately 800 MBytes of disk storage, an International Imaging Sys- 
tems (1 2 S) IVAS image display processor, and an 8-node JPL/Caltech Mark 
Illfp hypercube. The host machine will be changed to a Sun-4/260 during the 
first quarter of FY89 in order to provide a more flexible environment and to 
accommodate much higher data transfer rates utilizing new concurrent I/O 
capabilities. 

CIPE was designed around four major software modules; (1) user interface, (2) 
host system monitor, (3) hypercube monitor, and (4) application functions. A 
major design objective was to provide a powerful and flexible user interface for 
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efficient utilization of the system’s considerable computational resources. Sys- 
tem modularity provides relatively easy functional extensibility, both at the user 
level and the applications programming level. CIPE provides a number of utili- 
ties which greatly ease the applications programmer’s difficulties in dealing 
with a new machine architecture, i.e., the hypercube topology. We believe that 
the system described in this report provides a flexible framework within which 
to begin building a powerful user-oriented computing environment for high- 
performance science analysis workstations. 

This report is intended to serve both as an overview of the CIPE design and 
implementation philosophy as well as provide the level of detail necessary for 
both users and applications programmers to become familiar with the CIPE 
environment. Section 1 is a general overview of CIPE as an executive, includ- 
ing a description of its design objectives and the general implementation 
approach. Section 2 describes the three user interface modalities of command 
line interpreter, menu mode, and window mode. Section 3 describes the host 
system monitor functions with respect to generic operating system functions 
and concurrent system interface functions. Section 4 describes the hypercube 
monitor functions, including the interface mechanism to the host system and 
CIPE management of data and application programs. Section 5 describes how 
to write an application program in the CIPE environment, including utilization 
of user interface modes, host system monitor functions, and hypercube monitor 
functions. A set of built-in functions for image processing operations is also 
examined. Finally, Section 6 provides a look at future directions in CIPE 
development with respect to a general scientific computing environment for 
high-performance workstations. 



1. CONCURRENT IMAGE PROCESSING EXECUTIVE (CIPE) OVERVIEW 


CIPE was designed and implemented by the Image Analysis Systems Group for 
the purpose of utilizing various concurrent architectures in a high rate data pro- 
cessing environment. Concurrent systems provide greatly enhanced computa- 
tional power by integrating large numbers of processors into systems via vari- 
ous interconnection topologies. However, they do present significant program- 
ming difficulties due to their architectural complexities. In particular, utilization 
of such systems for interactive image processing requires a unique kind of 
software environment which shields users and programmers from architectural 
complexities while offering the computational advantages of concurrent sys- 
tems. 

1.1. WHAT IS AN EXECUTIVE? 

Though there is no written definition for an executive, in general, an executive 
is software which resides on top of an operating system and provides common 
resources to users and programmers within a well-defined application area. The 
common goal of an interactive image processing environment in a concurrent 
system configuration is the utilization of a concurrent architecture for faster 
processing of image data, visual presentation, and real-time user interaction. 
The shared resources include user interfaces, data manipulation, display, file 
I/O, and interfaces to concurrent systems. Therefore, an executive approach 
was chosen to provide a software environment (user and programmer) for con- 
current image processing. 

CIPE has distinctive characteristics as a concurrent system executive, as a high 
rate data processing executive, and as an interactive image processing execu- 
tive. As a concurrent system executive, it provides a programming environment 
which shields a programmer from architectural complexities while it utilizes the 
maximum potential of a concurrent system. As a high rate data processing exe- 
cutive, it provides a flexible file management scheme and efficient data manipu- 
lation and representation mechanisms. As an interactive image processing exe- 
cutive, it offers a friendly, flexible, and efficient user environment. 

1.2. DESIGN OBJECTIVES 

As CIPE is an executive serving three distinctive purposes, utilization of a con- 
current system, interactive image processing, and high rate data processing, it 
has three corresponding design objectives and one overall objective. 

First, the design objective as a concurrent system executive was to utilize a 
concurrent system to its full potential. The maximum concurrency of the system 
for data processing was pursued via devising appropriate data and program 
management schemes which utilize the architectural characteristics of a con- 
current system (interconnection topology, processing power, and memory sys- 
tem). 
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Second, the design objective as an interactive image processing executive was 
to provide an easy-to-use image processing environment which provides a user 
a wider range of expressional tools and choices of interaction levels. The 
expressional tools allow a user to carry out tasks efficiently. The multiple 
choices of a user interaction level, according to experience level and application 
needs, allow a user to be acquainted with CIPE easily while providing room to 
grow with it. 

Third, the design objective as a high rate data processing executive was to 
manage data efficiently so that its processing can be performed without waste- 
ful file transactions or data traffic between the host and a concurrent system. 
The main goal of the data management scheme was to overcome the data mani- 
pulation difficulties in a concurrent system with localized memory and a serious 
data transfer bottleneck. 

Finally, the overall design objective of CIPE is to provide an architecture- 
independent environment where neither a user nor a programmer needs to be 
involved in the system-dependent details related to the file system, display dev- 
ices, or concurrent systems. Such an environment is pursued by separating the 
executive into device-dependent and independent modules and coupling them 
with a set of generalized interface routines. The decoupling of the architecture 
dependency from the functionalities allows CIPE to be easily upgraded to 
future system configurations as well as maintain the transportability of the 
application programs. 

1.3. DESIGN IMPLEMENTATION 

The current implementation of CIPE uses the combination of a MASSCOMP 
5600 host computer and a MARK Illfp 8-node hypercube (Figure 1.1). CIPE 
consists of four modules: user interface, host system monitor, hypercube moni- 
tor, and a set of generic image processing functions. Each module is designed 
and implemented to achieve the overall design objectives of CIPE. 

As a user environment, CIPE provides a friendly user interface in three 
different forms: a command line interface, a menu interface, and a graphical 
windowing interface. The command line interface provides a simple interpreted 
programming language allowing interactive function definition and evaluation 
of algebraic expressions. The menu interface employs a hierarchical screen- 
oriented menu system for executing CIPE commands. The windowing interface 
is for graphical expression of commands and program flow. In this mode, the 
user performs functions through interactive creation of a graphical flow chart. 
Any of these interfaces can be used to control image processing operations 
under CIPE. 

The host system monitor handles overall system interactions and provides gen- 
eric image processing executive functions. The system management involves 
peripheral device handling, the concurrent system interface, and application 
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Figure 1.1 Concurrent Image Processing System Configuration 
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program execution. In order to develop an image processing executive for a vir- 
tual concurrent system environment, system setup procedures, data management 
schemes among multiple systems, and concurrent system interface methods 
were designed and implemented. Also, a data representation method was dev- 
ised to optimize the large volume data manipulation among file system, host 
system, and concurrent systems. 

Each concurrent system resident executive must implement unique architecture- 
dependent data and program management methods for optimal utilization of the 
architecture. The hypercube resident monitor allows CIPE to avoid data com- 
munication bottlenecks by keeping active data resident in the hypercube and 
minimizing application program space by downloading code as required to 
operate on the data. In order for data to be shared among several application 
programs with different data distribution requirements, an automatic data redis- 
tribution method is devised. 

The image processing function module is a non-resident component of CIPE, 
since each function is dynamically loaded only for execution. The executive- 
provided functions (partly implemented) include generic image processing func- 
tions, systematic flight data processing, multi- spectral data processing, and a set 
of data processing primitives for interactive algorithm development. 

The overall relation among modules is displayed in Figure 1.2. The example 
concurrent system resident executive in Figure 1.2 is a hypercube resident exe- 
cutive. The existing software tools employed for CIPE development are virtual 
display interface software developed by MIPL/JPL, and a general purpose menu 
manager software developed by Alan Mazer. CIPE is written in the C Pro- 
gramming Language and utilizes Yet Another Compiler Compiler (YACC) for 
command line parsing, and SunTool for the windowing user interface. The 
hypercube resident software is developed under the Crystalline Operating Sys- 
tem (CrOS) supported by Section 335/JPL using the C Programming Language. 
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Figure 1.2 CIPE Software Structure 
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2. USER INTERFACE 


The design philosophy behind the CIPE user environment is to provide the user 
a choice of interfaces. Though numerous "user friendly" interfaces have been 
developed, there is no single interface scheme that all users agree on; individual 
users have different conceptions of "friendliness" just as they have different 
levels of expertise and different processing needs. 

Basically, there are three types of user interface modes: command line, menu, 
and windowing. The command line interface (used by computer operating sys- 
tems, for example) imposes a rigid syntax structure and usually demands com- 
plete information about the operation to be performed when the command is 
entered. It is especially useful in a batch-oriented environment where a set of 
precomposed command lines can be utilized repeatedly, or when functions and 
expressions need to be interactively defined and evaluated. The menu interface 
offers a hierarchical organization and preformatted prompts for necessary infor- 
mation which a user can easily follow in real time. Its usage is for interactive 
data processing environments with limited amounts of user-provided informa- 
tion. The windowing interface provides another dimension to user interaction 
by offering a graphical expression. Its usage is for visually oriented data pro- 
cessing environments where a simple graphical expression can replace a com- 
plicated command line or menu input. 

CIPE provides all three types of user interface, allowing the user the advan- 
tages of each. The command line interface (Cli) provides a simple interpreted 
programming language allowing interactive function definition and evaluation 
of algebraic expressions. The menu interface employs a hierarchical screen- 
oriented menu system. The windowing interface is for graphical expression of 
commands and program flow. In this mode, the user performs functions 
through interactive creation of a graphical flowchart Any of these interfaces 
can be used to control image processing operations under CIPE. 

The windowing interface is implemented as a separate process which passes the 
user request to CIPE after the user expression is converted into an equivalent 
command line. This scheme was chosen to minimize the work of checking for 
valid user requests and to develop an executive-independent user interface. 

Cli and menu mode implement user input error-checking for all provided appli- 
cations to offer rapid response to input errors. Performing error checks at input 
time reduces the probability of execution error and prevents wasteful execution. 

In this section, the discussion of each user interface mode is focused on 
describing CIPE’s usage of each mode with respect to user interface organiza- 
tion and functionality through descriptions and examples. Details on the menu 
manager (Yamm) and windowing interface (Cipetool) are included in appen- 
dices. 
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2.1. COMMAND LINE INTERPRETER 

The first of the user interface approaches implemented in CIPE is the Com- 
mand Line Interpreter (Cli). The Cli makes available the basic capabilities of 
CIPE, including environment control, program execution, and the evaluation of 
functions and expressions. It also provides for the definition of Cli-interpreted 
functions and scripts, allows the creation of workspace collections of user- 
defined procedures, and provides more terminal independence than the other 
user interfaces. Interpreted functions may be expressed in terms of built-in 
primitives, compiled code, or other interpreted functions. The command line 
approach allows operations to be performed repetitively through looping and 
simplifies interactive evaluation of complex expressions using built-in and 
user-defined functions. Since most operating systems are command line based, 
the Cli approach also allows a user to escape CIPE execution temporarily and 
run operating system utilities such as to list a directory or to edit a file. 

This section discusses the implementation and use of the Cli, which has four 
parts: command line input and lexical analysis, parsing, code generation, and 
execution. Commands are taken from the keyboard or workspace, separated 
and unaliased into tokens in the command language, and parsed; commands 
taken from the keyboard may have been edited. The parser uses syntax- 
directed translation to build a pseudo-code program, which is then executed. 
The following subsections discuss each of these functions in detail. The sec- 
tion concludes with an annotated example showing how the Cli works in a typi- 
cal user session, and a brief discussion of the application program interface. 

2.1.1. Input and Lexical Analysis 

The input and lexical analysis phases of command line interpretation are 
straightforward, centered around the concept of input streams. An input stream 
corresponds to a source of command input As new streams are added, descrip- 
tors for previous streams are pushed onto a stack until such time as the new 
stream runs out of input. The first input stream in any session is the standard 
input, by default, the keyboard. As a user typing at the keyboard loads a previ- 
ously saved workspace, the workspace file becomes the current stream and the 
descriptor for the previous stream is pushed onto the stack. Workspace execu- 
tion continues until the workspace loads another workspace or ends, at which 
time the stack is adjusted accordingly. Edited command lines arc handled simi- 
larly, written to a file which is then opened as a stream and afterwards dis- 
carded. 

Command line interpretation starts with initializations: the allocation of initial 
buffer space, and the creation of an initial input stream descriptor. The 
remainder of interpretation is then a loop in which input handling is simply 
determining the current stream, managing pointers and status variables, provid- 
ing for editing, and reading a line. If the user requests editing of a previous or 
current command using CTRL E, the input code writes out what has been typed 
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so far, or if nothing, the last command, and allows the user to edit the com- 
mand using a standard full screen editor. This approach was chosen over more 
simple, line-based command editors both because of the ease with which a user 
can access a favorite editor and because CIPE command lines, such as those 
containing function definitions, are potentially so complex that a line editor 
approach is very difficult to use. Once edited to the user’s satisfaction, the 
descriptor for the previous stream is temporarily pushed onto the stack, and 
input is taken from a temporary file containing the user’s edited command. 
Implicit in the process of command input are management requirements such as 
the monitoring of buffer space (which may be automatically increased if neces- 
sary), the removal of unnecessary space and comments, and for edited com- 
mand lines, feedback of the final command line to the user. 

Actual lexical analysis is done by the function, yylex, generated from a legal- 
token specification by the Unix* utility lex. Supporting this lexical analysis are 
a variety of functions within Cli for tracing, line continuation handling, input 
buffer access, recognition of reserved words and their types, and error handling. 
Line continuations are usually provided automatically. Whenever a user enters 
a command line which is incomplete, either because some terminating delimiter 
has not been entered (such as a for loop started but not finished with an end or 
a function call with an incomplete argument list), or because the line ended 
with a two-argument operator, the Cli prints a continuation prompt, properly 
indented, to show that more input is expected. Alternatively, a user can indi- 
cate that more is to come by ending an input line with a backslash(\). 
Reserved words are recognized using a variety of lists stored within the lexical 
analyzer. Because reserved words such as multiword system attributes may be 
specified in several ways (with underscores between words of the attribute, or 
spaces, and with component words abbreviated), their recognition requires some 
local parsing to determine whether they are reserved words, legal variable 
names or simply errors. In addition to system attributes, reserved words 
include commands, command support words (e.g., step in for i=0 to 10 step 5), 
and boolean and keyword values (e.g., on). While error detection is largely 
done by the parsing, alerting the user is a function of lexical analysis, largely 
because the lexical analyzer has more information about the actual command 
lines as entered than does the parser. On errors, the lexical analyzer either 
prints the command line causing the error, together with an explicit error mes- 
sage and a carat O pointing to the location of the error within the line, or 
displays a workspace name and the number of the line within the workspace 
causing the error. 

2.1.2. Parsing 

The tokens taken from the input stream by the lexical analyzer are next fed into 
the parser, which attempts to assemble the tokens into a legal form, while at the 


* Unix is a registered trademark of AT&T Bell Laboratories. 



10 USER INTERFACE 


SECTION 2 


same time generating pseudo-code for the eventual execution of the command. 
The parser itself is generated by the Unix utility yacc from the Cli grammar 
definition file parser. y. 

The yacc language definition consists of two parts: productions and parse 
actions. The productions are defined formally by the following grammar in 
Backus-Naur Form: 


cmdjist <— cmdjist command 
I command 

command <— simple_cmd 
I cntl_struct 

simple_cmd <— exec_cmd 
I ! unix_cmd 
I output = expr 
I func_name ( actual_args ) 

I func_name 
I quit 

cnd_struct <— for var_name = expr to expr scmd_list end 

I for var_name = expr to expr step expr scmd_list end 
I while expr scmdjist end 
I if expr then scmdjist endif 
I if expr then scmd_list else scmdjist endif 
I if expr then scmdjist elsejf Jist else_list endif 

exec_cmd <- set entity attr to expr 
I set attr to expr 
I turn bool entity attr 
I turn bool attr 
I functions 
I symbols 
I traces 

I print expr Jist 
I show func_name 

I define func_name ( formal_args ) cmd_list end 
I load ws_name 
I save ws_name 
I edit ws_name 

I read var_name from filename 
I write var_name to filename 
I display var_name at_loc 
I menu 
I nomenu 
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I quit 

output <— var_name 

I var_name [ indexjist ] 

scmdjist <— scmd_list ; simple_cmd 
I simple_cmd 

else_if_list «— else_if_list else if expr then scmdjist 
I else if expr then scmdjist 

elsejist <— else scmdjist 
I e 

entity <— cube I gapp I system 

attr <- dimension I num_procs I topology I priority I logging 
I lextrace I parsetrace I codegentrace 
I exectrace I symtabtrace I functabtrace 

formal_args <— e 

I var_name 

I formal_args , var_name 

ws_name <— expr 

filename «- expr 

at Joe <— e 

I at expr , expr 

indexjist <— indexjist , index 
I index 

actual_args <- e 

I exprjist 

index <— expr 

I expr : expr 

exprjist <- expr 

I exprjist , expr 

expr «— expr op2 expr 
I opl expr 
I var_name 

I var_name [ indexjist ] 
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I func_name ( actual_args ) 

I ( expr ) 

I constant 

constant <— single_value 
I { value_list } 

value_list <— value_list , single_value 
I single_value 

single_value <— integer 
I float 
I string 
I enum 

op2 <- && I || I & I | I * I < I <= 

I == I != I >= I > I * I / I + I - 

opl < I ! I ' 


A few formats and details are omitted here where the rules are generally agreed 
upon, such as for the formation of floats. Variables are not explicitly typed; 
types are determined at run-time and functions do type conversion as necessary. 

Yacc’s output code uses shift-reduce parsing with single-token lookahead to 
reduce every input line to a valid command. As tokens are received from the 
lexical analyzer and shifted onto a stack, the parser attempts to reduce (com- 
bine) sequences of tokens appearing on the right side of one of the listed pro- 
ductions. When several tokens can be reduced to a higher-level element of the 
grammar, called a non-terminal to distinguish it from a terminal or reserved 
word in the command language, they are replaced on the stack by the non- 
terminal, which is in turn compared against the right side of the productions 
above. Ultimately, the group of tokens forming the input line reduce, through 
many intermediate steps, to a cmdjist. Note that a legal input line may actu- 
ally have multiple commands according to this grammar. No command delim- 
iter is necessary; the grammar is designed such that successive commands may 
be expressed on the same line unambiguously. 

In addition to the productions listed above, the yacc input definition contains 
parse actions. Parse actions are invoked whenever a sequence of tokens or 
non-terminals reduce to a higher-level non-terminal, and represent most of the 
code in the yacc input definition. They fulfill two functions: to assist in pars- 
ing, and to create the pseudo-code which is the ultimate product of the parser. 
For example, when an integer value is sent by the lexical analyzer, the parser 
recognizes that and reduces it to the non-terminal single_value. The parse 
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action for the reduction is to print out a trace, if the user has requested parse 
tracing, allocate storage and save the value in the symbol table, and then asso- 
ciate the index of the value in the symbol table with the new non-terminal on 
the parse stack. Similarly, the non-terminal single_value will eventually be 
used along with other input in the formation of one of the non-terminals con- 
stant or value Jist, depending on whether or not it was preceded by a brace ({). 
If part of the non-terminal valuejist, the parse action combines the value 
represented by single_value with the other values in the value list, associating 
with the new non-terminal this expanded list of values. Ultimately, the instruc- 
tion using this value will be generated by yet another parse action looking at a 
correspondingly higher-level group of non-terminals. 

These and similar parse actions are applied at every step in the parsing of the 
grammar until a program has been created. Other parse actions handle such 
things as intelligent error detection and recovery, table lookups and manage- 
ment, backpatching (changing previously created code based on new and previ- 
ously unavailable information), code segment management (described in more 
detail in the next section), and the creation of temporary variables. 

2.1.3. Code Generation 

A large part of parser action work is in the generation of pseudo-code instruc- 
tions for execution of the command. The code called by these actions forms 
the third part of the Cli, code generation. As the idea of streams is fundamen- 
tal to understanding command input and lexical analysis, so code segments are 
central to code generation. A code segment is a data structure containing the 
name of a user-defined function, a pointer to the compiled code, a symbol table 
and function table, and a pointer to a parent code segment. One code segment 
is set up by default when the user starts up CIPE. Commands typed at the key- 
board are compiled and described by this code segment, including any func- 
tions defined at the keyboard level and any symbols created interactively. 
When a workspace is loaded, a descriptor is created for it, with the original 
code segment as parent, and execution shifts over to the workspace. The use of 
code segments allows easy grouping of symbols and subordinate functions in 
the proper context, and allows CIPE to quickly find the correct data or function 
when a specification is potentially ambiguous. 

The code generation functions fall into two groups: code segment maintenance 
and support, and instruction generation. Code segment maintenance routines 
include code to create new code segments (as when executing a DEFINE com- 
mand), add instructions to the current code segment, and return to a previous 
code segment. Support routines store and manage constants in the symbol 
table, perform compile-time type conversions, disassemble instructions for 
user-defined workspace and function listings, and create temporary variables. 
Instruction generation routines take information grouped by the parser and 
translate it into individual instructions. Most commands recognized by the 
parser translate into a specific instruction which is generated by a corresponding 
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code generation routine. For example, the routine cipe_arith_op is called when 
the parser gets a token group of the form constant + constant. It generates an 
addition instruction, creating a temporary variable, if necessary. Similar code 
generation routines create instructions for assignments, subscripting, function 
calls, and the other language features. In the case of branching as part of a 
looping construct, where all the available information for instruction generation 
may not be available until the loop is completely parsed, parser actions direct 
the routines to produce skeletal code which is then backpatched, or filled in as 
the information becomes available. Code generation for the assignment instruc- 
tion attempts to modify previous code to make the assignment instruction and 
the resulting overhead unnecessary. 

2.1.4. Execution 

The fourth and final step in command line interpretation is taking the instruc- 
tions created by the code generation routines and executing them. At this 
point, the lines between the user interface and the core of CIPE begin to blur. 
Execution of the generated instructions is distinctly a Cli responsibility, but this 
responsibility is implemented using basic CIPE system functions. Not all code 
generated is executed immediately either. If a user types in a function 
definition using the DEFINE command, two pieces of code are generated. The 
first of these is the code for the function being defined. The second is a very 
short program defining the function as a function in the current code segment. 
This definition basically associates the name of the function with the location of 
its code segment in the current function table. The function defined, although it 
has been input, parsed, and translated into pseudo-code, is not executed until a 
call to the function takes place. Only the definition instruction is actually exe- 
cuted immediately. This distinction is very important. 

When code is executed, the process is straightforward. Execution is imple- 
mented as a loop where each iteration grabs an instruction from the current 
code segment, displays it if requested by the user using the TURN ON EXEC 
TRACE command, and then executes it. Generally, control will then pass to 
the next instruction which will be executed in the next iteration of the loop. 
Branches and QUIT instructions may be used to alter the normal flow. All 
instructions do run-time error checking and type conversions as necessary. 
Arithmetic built-ins are executed on the coprocessor if the data size is 
sufficiently large; otherwise they are executed by the host system. When a call 
to a user-defined function is executed, the function is located in the current or 
an ancestor code segment’s function table and the current code segment is 
replaced with the code segment of the function being called. When execution 
of that function finishes, possibly after calling other functions, the original sec- 
tion of code resumes execution. Recursion is not permitted. Compiled func- 
tions may also be called, but do not result in any changes in the current code 
segment. 
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2.1.5. User Summary and Example 

Subsections 2.1.1 through 2.1.4 have described in some detail the major parts 
of command line interpretation, that is, input and lexical analysis, parsing, code 
generation, and the eventual execution. This section presents a more informal 
description of the available commands and an example showing their usage in a 
typical terminal session. The commands are as follows: 

set attr to expr 
turn bool attr 

Attr is an attribute (e.g., coprocessor, display device, logging). 
An expression is formed using (possibly subscripted) variable 
names, function calls, operators, and constants (strings, numerics, 
keywords). C language operators work with the same pre- 
cedence as in C. Constants may be multivalued if values are 
separated with commas and the constant is delimited by left and 
right braces. Bool is a boolean value (i.e., on, off). 

functions 

symbols 

Display the current functions and symbols. 


traces 


Show the traceable system parameters and their trace status, 
print expr_list 

Display the specified value(s). Multiple values should be 
separated with commas. A newline is added automatically. 

show func_name 

List the specified user-defined function in a pretty format, 
define func_name ( formal_args ) cmd_list end 
Define a new function, 
load ws_name 

A workspace is a set of commands or functions definitions or 
both. They are stored as text on the disk. A wsjxame is a 
quoted file specification. Load retrieves a workspace from the 
disk. Multiple workspaces may be loaded at the same time. 
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save ws_name 

Save all current user-defined functions to the disk, 
edit ws_name 

Edit the specified workspace using the vi full screen editor. 

read var_name from filename 
write varjiame to filename 

Read or write using specified variable and file filename. 

display varjiame 

display varjiame at line , sample 

Display image on current display device at top-left of screen or 
position line, sample. 


menu 

nomenu 

Enable and disable menuing. If in a workspace file, these com- 
mands do not take effect until execution of the entire file has 
completed. 


quit 


Exit CIPE. Contiol-D works also. 

! unix_cmd 

Performs the specified Unix command, 
output = expr 

Assign the value of expr to variable or subscripted variable out- 
put. 

func_name ( exprjist ) 
func_name 

Call function func_name. 

for var_name = expr to expr cmd_list end 

for var_name = expr to expr step expr cmd_list end 
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while expr cmd_list end 

if expr then cmdjist endif 

if expr then cmdjist else cmdjist endif 

if expr then cmdjist else if expr then cmdjist... else cmdjist endif 
if expr then cmdjist else if expr then cmdjist.. endif 

Cmdjist is a list of commands from Section 2 above; these are 
easiest to read on separate lines, but they can be ran together if 
desired. Control structures are not nestable at the moment. 


The following is an example of a terminal session. A pound sign (#) indicates 
the start of a comment These comments need not be typed in as part of the 
command lines, but are useful in complex user-defined functions. All text fol- 
lowing a pound sign is ignored by CIPE. User input is underlined. 


unix% cipe 

CIPE Version 3.2 # local startup script performs 

# user-specific initializations on startup 


> set coprocessor to cube # grab the hypercube 

> turn on logg in g # start session logging - this could 

# have been done in startup script 

# automatically 

> set disp dev to ivas # allocate ivas - note abbreviations 

> read aisa from "/ufs/images/aisa" # load an image 

> filtered = boxfilter('aisa.3.3') # programmer-defined function returns result 

> stretched = stretch(filtered) 

> display stretched # keywords for output include print, write, 

# and display 


# At prompt, define general procedure to do the steps above 


> define filtnstretchfimage.filt nl.filt ns) 

? load imag e 

? hoxfilterlimage.filt nl.filt nsl # do filter in place here 
? stretch(imag e) 

? display imag e 
? end 

> 'E 


# user decided to add to previous 

# command line 
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... vi ... vi ... vi ... 

# on exit from vi, system executes new command 

> define filtnstretch(image,filt_nl,filt_ns) 

? if filt_nl < 1 then 

? print "Number of lines (",filt_nl,") is too small" 

? filt.nl = 1 

? endif 

? if filt.ns < 1 then 

? print "Number of samples (".filt.ns,") is too small" 

? filt.ns = 1 

? endif 

? boxfilter(image, filt.nl, filt.ns) 

? stretch(image) 

? line=l 

? for sample= 1 to 511 step 32 
? display image at line, sample 

? end 

? print "The new image is displayed now!" 

? end 

> 

> filtnstretch("/ufs/images/aisa".3.3) 

The new image is displayed now! 

> save "mvfunctions" 

> !ls -1 mvfunctions 

-rw-r--r- 1 cipe 4322 Jul 7 

> quit 

2.1.6. Application Program Interface 

The Cli application program interface is extremely simple. When a compiled 
application function is called, Cli parses the command line, checks the function 
dictionary to find the location of the code, and invokes the function. Descrip- 
tors of the arguments passed to the function by the user are stored internally. 
The application program accesses these descriptors as an external array and 
calls CIPE system routines to extract the values of the arguments passed on the 
command line. When an argument is an expression rather than a symbol, CIPE 
evaluates the expression and creates a temporary symbol to use in the argument 
list. If the function has a return value, the symbol designated by the user for 
the result is also referenced as an external and used by the application program- 
mer as storage for the final result 


# user tests function 


# user saves function on disk 

# for future use 

# check directory for saved 

# workspace 
13:05 myfunctions 
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2.2. MENU 

The menu interface of CIPE serves several purposes: self-orientation to CIPE’s 
organization, a simple environment for inexperienced users, interactive input 
verification, and functional grouping of CIPE capabilities. The entire CIPE 
functionality is accessible by flipping through menus using menu control keys, 
allowing one to quickly grasp the organization and usage of individual CIPE 
commands. Each activated command displays prompts for required user inputs 
and help can be made available for each input field so that inexperienced users 
can easily follow the procedure. The validity of input may also be checked in 
real-time and proper error messages displayed so that users can correct input 
before actual execution takes place. The hierarchical organization of the menus 
allows grouping of related functions. This functional grouping enhances the 
menu entry selection process, since a user can scope CIPE according to his/her 
processing needs. 

Menu mode is implemented using Yamm (Yet Another Menu Manager), a gen- 
eral purpose menuing package. Design details of Yamm are included in 
Appendix G and an implementation example is provided in Section 5. This 
section is devoted to describing the utilization of the package in CIPE to pro- 
vide a menuing user interface to serve the purposes presented above. 

2.2.1. Menu Format 

Yamm employs three windows: a menu window, an application I/O and data 
entry window, and a status window. The menu window displays the submenus 
and functions available at the current level of the menu tree. The menu hierar- 
chy is specifiable on a per-user basis using menu configuration files, allowing 
individual users to customize the environments. The menu configuration is 
structured in a multibranched tree fashion, where the leaf node is connected to 
a corresponding routine name as shown in Figure 2.1. 

Currently, accessible submenus and applications are selected either by number 
or by using arrow keys to move to the desired selection. If a submenu is 
selected, its set of menus and accessible functions replaces those of the previ- 
ous menu in the menu window. When the selected submenu entry is a leaf 
node in the menu configuration, the corresponding function becomes activated. 
The interaction between a user and the activated function takes place in the 
application I/O and data entry window. 

The application I/O and data entry window serves a dual purpose. During exe- 
cution of user programs, it displays application output and system error mes- 
sages. During application-requested data entry, the window displays a data 
entry form for specification of a given command’s inputs. A parameter may be 
classified as required when a value must be given by a user or defaulted. For 
the parameters with default values, the default values are automatically 
displayed and a user may accept or change them. Individual parameters may 
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Figure 2.1 Menu Structure 
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also have help and parameter-specific error checking. For parameters with just 
a fixed number of valid values, the key combination shown in the status win- 
dow next to Next Value may be used to step through the possibilities. See 
Appendix G for the complete set of Yamm capabilities. 

The status window displays the name of the current menu and the keys used for 
the available functions in context. For example, during parameter entry the 
window shows keyboard mappings for Return to Menu, Help, End Data 
Entry, etc. When waiting for a submenu or application selection, the menu 
status window shows mappings for such things as Previous Menu and Exit. 
Keyboard mappings are determined automatically based on the type of terminal 
in use, but may also be specified in the code by the programmer or in user- 
specific menu configuration files. 

2.2.2. CIPE Menu Configuration 

The CIPE menu hierarchy is structured so that a user can easily understand and 
access the available functions. The hierarchy has two major components: CIPE 
commands and application functions (Figure 2.2). The first group includes 
entries for coprocessor-independent functions such as help, system setup, sym- 
bol management, display, and plot utilities. The application functions menu 
will be modified as different application functions are developed. The current 
applications menu includes a set of generic image processing capabilities. The 
CIPE menu configuration can be found in Appendix I under menuconfig and the 
link between the function entries and corresponding function names are defined 
in menus.h, also in Appendix I. 

The symbol management entry is a submenu with a set of lower level entries 
including List, Assign, Read, Save and Delete. The List entry is for listing 
out the the currently defined symbols. The Assign entry allows the user to 
assign a set of values to a symbol. The Read entry associates an existing file 
with a symbol. The Save entry is for saving symbol values to files. Delete 
deletes specified symbols from the system. Figure 2.3 illustrates the symbol 
manipulation menu where the Read function is activated. Actual execution of 
these functions is discussed in Section Three under Data Management (Section 
3.2). 

Display capabilities include display device allocation, stretches, image display, 
histograms, and display control. Display devices may be allocated in black and 
white, color, or pseudo-color modes. The Stretch entry allows linear and non- 
linear lookup table manipulations. Both two- and three-dimensional image data 
may be displayed and used in histograms. Display control capabilities include 
cursor access and control, and erase and zoom operations. Figure 2.4 shows 
the display menu where Draw function is activated. Plot capabilities include 
multi-spectral plotting and three-dimensional image plotting where pixel inten- 
sity is represented as height. 
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Figure 2.2 Root Menu of CIPE 

Image processing applications functions are subdivided into Enhance (Image 
Enhancement), Geom (Geometric Transformation), Classify (Scene 
Classification), Builtin (Built-in Functions), and Appl (User Applications). 
Image enhancement capabilities include spatial convolution, histogram manipu- 
lation, frequency domain filtering (low/high/band pass) and statistical (median) 
filtering. The geometric operations include tie-point-oriented geometric correc- 
tion, map projection, and image resizing. The classification functions include 
textural scene segmentation and spectral classification. The user application 
entry activates user-developed application programs compiled outside of CIPE. 
Details on writing application programs for CIPE are discussed in Section 5, 
Application Programming in CIPE. 

Along with these other capabilities, CIPE provides a set of built-in functions 
for arithmetic, relational, and logical operations on scalar and multi-dimensional 
data. Each of these takes one or more symbols as arguments and returns a 
symbolic result. Figure 2.5 shows the image processing menu where the Buil- 
tin function is activated. 
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Figure 2.3 Symbol Menu 
2.2.3. Parameter Field Structure 

Apart from determining a menu hierarchy, the other major task in implementing 
the menu interface is the design of individual data entry forms to be displayed 
by Yamm when specific CIPE commands or application functions are 
requested. For each input parameter Yamm needs to know such things as a 
screen location, prompt message, data type (for Y amm internal error checking 
and conversion), and information about number of values, default values, and 
field widths. CIPE provides this information to Yamm for each parameter field 
and Yamm then uses these in displaying the data entry form and processing 
input. An example parameter specification internal to CIPE and its Yamm 
interpretation follows. Function-dependent error checking and interactive help 
are also available and they are discussed in the next two sections. 
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Figure 2.4 Display Menu 


param_count = 4; 

def(params,0, "input symbol name ",STRING,input,WID,32, 
LINE,2,REQ,END); 

def(params,l,"outut symbol name ",STRING, output, WID,32, 

LINE,3,REQ,END); 

def(params ,2, "filter window(nlw,nsw) ",INT, window, INCR, 4, 
WTO, IODINE, 4, DUP,2,REQ,END); 
if (getpar(params,param_count,check_filter,heIp_filter)) return; 


When the statements in the example are executed by Yamm, a menu shown in 
Figure 2.6 will be displayed in the terminal screen. 
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Figure 2.5 Image Processing Menu 
2.2.4. Error Handling 

Another part of parameter entry definition is the specification of an error check- 
ing function by which input validity may be checked as input is entered. This 
interactive user input verification significantly enhances interactive use of CIPE 
because it prevents wasteful execution of invalid input parameters. The error 
checking mechanism is provided by Yamm and the actual value checking is 
provided by CIPE. Yamm’s input processing routine (getpar) allows optional 
specification of an error checking routine. When an error checking routine is 
provided, Yamm calls the specified routine for each parameter input value. The 
correct error checking steps are then selected based on the parameter number. 

CIPE provides an error checking routine for Yamm to call for each function. 
Each routine is composed of several sets of error checking steps, each set cov- 
ering a specific input field. The error checking steps evaluate the input value 
and print a proper error message if the value is found to be invalid for the 
activated function. Since syntax errors are checked by Yamm, only validity 
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Figure 2.6 Spatial Filter Parameter Menu 

checking of entered values is necessary. Yamm uses the last two lines of the 
application I/O and data entry window for the error/waming messages. 

As shown in the example of the error checking routine for a spatial filter pro- 
gram, error conditions are handled for each parameter using a case statement. 
In case 1, the input symbol name is checked for existence and a message is 
printed on error. In case 2, the output symbol is checked for non-existence and 
a warning message printed if an existing symbol may be overwritten. In case 
3, the window parameter is verified for a valid range as well as an odd value. 
An illegal value is replaced with the previous valid value or default value (if 
any) when the error message is displayed. 
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check_filter(params, number, value) 
struct param *params; 
int number; 

union (int i; double f; char *s;} value; 

{ 

int error, whereis; 

error = 0; 

switch(number) { 

case 0: whereis=cipe_get_symbol_index(value.s); 
if (whereis == NO_SYMBOL) error = 1; 
if (error) error_print("symbol does not exist"); 
break; 

case 1: whereis=cipe_get_symbol_index(value.s); 
if (whereis != NO_SYMBOL) error = 2; 
if (error) error_print("symbol already exists"); 
break; 

case 2: if (((value.i) % 2) == 0) error = 3; 

if (error) error_print("must be odd number"); 
break; 

} 

return(error); 

} 


2.2.5. Interactive Help Messages 

Similar to the error checking mechanism, Yamm provides a help mechanism 
for individual input fields and CIPE provides the actual help messages. A help 
routine may be provided for each Yamm-invoked function; the routine name is 
passed to Yamm as a parameter of getpar. The help routines are structured and 
called similar to the error checking routines. 

In order to display a help message, a user presses the HELP key as defined by 
the status window. Then Yamm calls the help routine to print the correspond- 
ing message. Help message examples include required value range, more 
detailed prompt messages, parameter usage, and various function-dependent 
guidelines. 

The help routine for the spatial filter program is illustrated as an example. 
Some parameter fields (such as that for the file name) do not require help 
because they are very straightforward. Others (such as the filter window 
parameter field) provide an explanation of usage and a proper value range. 
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help_filter(params, number) 
struct param *params; 
int number; 

{ 

switch(number)( 

case 0: printf("input data must be two dimensional image"); 

break; 
case 1: break; 
case 2: 

printf("size of a weight matrix, must be odd number"); 
break; 

} 

} 


2.3. CIPETOOL 

Cipetool is a graphical user interface that serves as a front-end to CIPE. The 
freedom which allows a user to express his/her processing needs in the most 
direct fashion is highly correlated with the user’s performance. The main goal 
of this user interface mode is to expand the user’s expressional freedom beyond 
the limited keyboard typing of Cli and Menu mode of CIPE. Currently, a very 
limited conceptual level of the graphical interface has been implemented using 
iconic manipulation, based on the Sunview Windowing system supported by 
Sun Microsystem. This section describes the current status of Cipetool as an 
iconic interface mode to CIPE with respect to icon implementation and interac- 
tion with CIPE. The direction of the future Cipetool is also discussed. 

2.3.1. Icons 

Current Cipetool employs three types of icons: data, function, and device. The 
data type is subdivided into constants, arrays, and images. The constant and 
array icons are for entering immediate values to an activated function. A char- 
acter string value is represented using a constant icon and it is indicated by sur- 
rounding it with double quotes. The image icons are associated with image 
files in the system and their sizes are made to be proportional to the actual 
image’s size. An image icon can be manipulated to select a subsection of an 
image by specifying the starting and ending locations using a mouse. The func- 
tion type includes all of the CIPE data processing functions. The function icons 
are associated with data processing functions of CIPE and their sizes are deter- 
mined based on the function descriptions (prompt messages, numbers) of input 
and output parameters provided in the function dictionary. The input and output 
entries of each function are designated with prompt message boxes. A user 
must provide input parameter values by connecting proper input data icons to 
the prompt message boxes of a function icon before execution of the function. 
A prompt message box is referred to as a connection box since it is used for 
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connecting a data icon. Cipetool creates an output icon after the function is 
completed based on the data type (image, array, constant) and the size of the 
output. A display device is only device icon implemented at this stage. Thus, 
there are five icons, constant, array, image, function, and display device. 

A user manipulates the data and function icons using Cipetool-provided icon 
control buttons. There are four control buttons, constants, arrays, listjmages, 
and list_functions. The constant or array button creates a constant or array 
icon respectively, and the user must supply the data value(s). When a user 
wants to access an image file, he/she opens the image icon control menu by 
pressing the listjmages button which displays a list of existing images. Upon 
selecting an image file, an image icon representing the selected image is 
created. A user may manipulate the location of the icon arbitrarily using the 
Sun mouse. Similarly, a user can choose a data processing function from the 
function control window. 

The iconic expression illustrated in Figure 2.7 describes the iconic manipulation 
procedures involved in performing a 3 by 3 box filtering on the image file 
"girl.bw". First, a user examines the list of existing image files and selects the 
"girl.bw" using the listjmages menu. Cipetool creates an image icon 
representing the girl.bw file. Second, the user selects the filter function using 
the list Junctions menu. The filter function icon is created with prompt mes- 
sages for input image, filter window size, and output storage. Third, the user 
creates a constant icon for the window size value, 3. Fourth, the user draws 
lines between the input data icons and the connection boxes to supply the 
inputs for the filter function. Finally, he/she activates the function. When the 
filter function is completed, Cipetool displays the output image icon represent- 
ing the filtered image. 

One of the important usages of Cipetool user interface mode is the peripheral 
device interaction. For example, when a user wants to display an image file in 
the display device, he/she creates an image icon representing the image file and 
simply places the image icon in a desired location of the display device icon as 
shown in Figure 2.7. The image will be displayed in the associated display dev- 
ice on the corresponding location. Such interaction is much simpler than speci- 
fying the display location in pixels. The display icon is created when it is allo- 
cated. Similar interaction can be applied to other peripheral devices. 

2.3.2. Interface to CIPE 

Cipetool interacts with CIPE via an interprocess communication mechanism of 
UNIX. Cipetool converts the iconic user input into CIPE command lines and 
pipes them to CIPE Cli mode for execution. Cipetool utilizes the function dic- 
tionary file for prompt messages of input and output arguments, data types, 
default values, and help messages for the activated function. The description of 
the boxfilter function (see Figure 2.7) in the function dictionary is shown 
below. 


List Functions ) ( Enter constant ) ( Enter array ) f Quit 
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Figure 2.7 Iconic User Interface Example 
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function boxfilter( 
input, "IN", STRING 
input, "Width", INT 
input, "Height", INT 
output, "OUT", STRING) 

help "replaces the pixel with the average intensity of the box" 
pathname "/ufs/cipe/appl/cp/cpbox" uses hypercube 


In order to incorporate the data representation of CIPE, the data icons must be 
associated with symbol names. Cipetool employs a symbol name convention by 
attaching an index to the icon type (constant, array, image). For example, the 
symbol name of the first image icon is "image 1". When the data type is not 
known, a temporary name is given to the icon. After the filter function is com- 
pleted, Cipetool checks the description of the output symbol temp from the 
symbol table. The symbol table content is received from CIPE by issuing the 
CIPE command symbols. Then Cipetool renames the temporary symbol name 
and displays the output icon using its data type and size. The output of the 
filter function is renamed to "image2" since the data type is image and it is the 
second image symbol created in Cipetool. The CIPE Cli command sequence 
for the iconic expression shown in Figure 2.7 involves the following steps. 

1. read (imagel) from file (girl.bw) 

2. constl = 3 

3. temp = filter(imagel, constl, constl) 

4. symbols 

imagel ( girl.bw ) IMAGE 512 lines 512 samples 

temp IMAGE 512 lines 512 samples 

5. image2 = temp 

6. display image2 at 100, 100 


2.3.3. Future Direction 

Current Cipetool is a prototype version implemented to demonstrate the concept 
of the graphical user interface The iconic manipulation was found to be some- 
what cumbersome to compose a complex command line. The interaction 
mechanism between CIPE and Cipetool needs to be carefully reviewed to 
improve the graphical user interface. In order to overcome the limitations of the 
iconic manipulation, the future Cipetool will implement a complete set of 
graphical expressions including conditionals, branches, loops, and various pro- 
cedural descriptors. With the graphical expressions, a user can describe his/her 
task in a flowchart-like fashion. The graphical expression will be extended to 
manipulation of a complex system environment with several concurrent systems 
and various peripheral devices. Most importantly, the future Cipetool will be 
evolved to be an executive independent front-end process by implementing an 
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interface layer which will convert the graphical expressions to a proper 
sequence of command lines for various executives. The virtual executive front- 
end is an extremely important issue to many existing executives, since it does 
not require a program conversion process, which is often too expensive. 
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3. HOST SYSTEM MONITOR 

The CIPE system configuration includes a host system and one or more con- 
current systems. Thus, the executive is divided into a host resident part and the 
concurrent system resident part. The host resident part, referred to as a host 
system monitor, handles overall system interactions and provides generic image 
processing executive functions. The system management involves peripheral 
device handling, the concurrent system interface, and application program exe- 
cution. The current implementation of the host monitor resides in a 
MASSCOMP 5600 system with an IVAS display device, with near-term exten- 
sions planned for Sun-3/Sun-4 workstations. 

In order to develop an image processing executive for a virtual concurrent sys- 
tem environment, system setup procedures, data management schemes among 
multiple systems, and concurrent system interface methods were designed and 
implemented. A data representation method was also devised to optimize the 
large volume data manipulation among file system, host system, and concurrent 
systems. In this section, the host system monitor is described with respect to 
its four functions: system setup, data management, file management, and con- 
current system interface. 

3.1. SYSTEM SETUP 

The system setup function is designed for interactive system configuration. 
The initial system configuration may be modified using a user-provided .ciperc 
file. The setup parameters include selection of a concurrent system 
(none/cube/gapp) and a display device (none/ivas/raster/sun), setting of debug 
level, session log option, and trace level for program execution. The setup 
parameters can be entered in a menu mode using a setup entry as shown in Fig- 
ure 3.1, or at the Cli prompt using individual commands, as shown in Figure 

3.2. 



I 
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*L=Refresh 
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KPD -=Next value 

KPD ENTER=End data entry 



Figure 3.1 Setup Menu 

> set coprocessor to cube 

> set cube dimension to 3 

> set display device to ivas 

> turn on appl trace 

Figure 3.2 Cli Setup Sequence 


3.1.1. .ciperc file 

A user provides his/her own default system environment via a .ciperc file in 
his/her home directory, which is very similar to the .login file or .cshrc file of 
UNIX. When CIPE is activated, the .ciperc file is read in as a script file and 
the commands in the file are executed. The example .ciperc file which follows 
will print "Welcome to CIPE" as CIPE is activated, the main menu will be 
displayed, and the session will be logged until the session log option is 
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explicitly turned off. 

print "Welcome to CIPE" # print a greeting as CIPE starts 

turn on logging # turn the session log option on 

menu # set user interface to menu mode 


3.1.2. Coprocessor Initialization 

When a coprocessor is selected, CIPE deallocates any currently allocated copro- 
cessor and allocates the selected coprocessor. The deallocation process warns a 
user if there are any unsaved data sets before actual deallocation. The Mark 
infp hypercube, like some other possible coprocessors, is a single user 
machine. Interactive coprocessor allocation/deallocation allows time sharing of 
a coprocessor among multiple users. 

In the case of hypercube allocation, CIPE invokes the hypercube’s Crystalline 
Operating System (CrOS)* routine, cubeld(dim,ELT_MONITOR ), where the 
variable dim has the dimensionality of a hypercube and the ELT_MONITOR is 
the name of the hypercube executive file name. This command resets the hyper- 
cube according to the specified dimension and loads the executive in all nodes 
of the hypercube. 

The allocation process for an NCR Geometric/Arithmetic Parallel Processor 
(GAPP) system consists of loading the GAPP executive on the program 
memory in the GAPP controller board and the GAPP array memory initializa- 
tion. The GAPP system executive will be discussed in a separate report in the 
future. 

3.1.3. Display Device Selection/Allocation 

A display device can be arbitrarily allocated and deallocated but only one 
display device can be selected at a given time. The initialization of a display 
device includes configuration of a video monitor, look-up table composition, a 
look-up table connection to each image frame, and cursor activation. 

The display utilities were developed using the virtual display device interface 
(VRDI) software developed by MIPL/FPL. The VRDI offers interfaces to most 
commercially available frame buffers including Ramtek, Raster-tech, Ivas, and 
Deanza. The CIPE display utilities are described in detail in Section Five. 


* CiOS is a product of the JPL/Caltech Concurrent Computation Project 
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3.1.4. Session Logging 

The session log provides a record of a user session by copying the standard 
input and output statements to a session log file. The session log option plays 
an important role in an interactive image processing environment by keeping 
track of what a user has done. 

A session log file is generated per CIPE session and its name convention is 
session.log. pid where the pid is the process identification number of the ses- 
sion. The session log option can be turned on and off during the session freely. 
When the log option is turned off the session log file is closed with a time tag, 
and when it is turned back on after a while, the session log file is opened with 
an update option and the time the log is turned on is recorded. 

3.1.5. Trace Flags 

A set of trace parameters which can be set for tracing specific execution of 
functions is installed for optional display of program flow. The installed trace 
parameters include command line interpreter function-related traces 
(parse_trace, lex_trace, codegen_trace, functab_trace), a symbol table 
manipulation-related trace (symtab_trace), hypercube executive traces 
(cube_command, cube_data, cube_symbol), a general CIPE execution trace 
(exec_trace), and an application program execution trace (appl_trace). Only 
the appLtrace can be turned on by both Cli and menu mode for a typical user. 
All of the other traces can be turned on only in Cli mode and are intended for 
CIPE system program developers. A debug level is also provided to control 
the detail of the trace statements. 

3.1.6. Function Dictionary 

CIPE employs a function dictionary file to support Cipetool and Cli user inter- 
face modes. When an application program is installed in CIPE, the program 
function name and its description are recorded in the function dictionary file by 
the CIPE system manager. Cipetool displays an icon of a user-requested func- 
tion with input and output parameter fields, and the Cli parses and verifies the 
user input command line based on the information provided in the function dic- 
tionary. 

The function dictionary file contains descriptions of available functions and pro- 
cedures. The application programs that return output data are defined to be 
functions and the application programs with no returned value are defined to 
be procedures. The function description consists of function name, its input 
argument list, return argument list, and pathname list. The argument structure 
consists of input or output specification, data type, prompt message, and default 
value. The pathname shows a corresponding application program name and the 
applied system where the function can be executed. The procedure description 
consists of the same items except that there is no return argument list. 
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FUNCTION name ( argument-list ) 
RETURNS ( argument-list ) 

HELP " help message" 

PATHNAME location-list 

PROCEDURE name (argument-list) 
PATHNAME location-list 

where an argument-list is structured as 

[access-type] [value-type] prompt-message 


for 


access-type INPUT or OUTPUT 

value-type INTEGER, FLOAT, DOUBLE, STRING, or BOOLEAN 
prompt-message ” string ” 

and location-list is structured as 

pathname USES system 


The current implementation is limited to one return argument and one path- 
name. As various concurrent systems are added to the CIPE environment, each 
function will have multiple pathnames showing application program file names 
for corresponding system architectures. Architecture-independent programming 
can be supported via a function dictionary file where an application program 
invokes a function, and its architecture-dependent program is activated for a 
system allocated at the time. 

An entry of the CIPE function dictionary is shown in example where the func- 
tion name is filter and it expects five input arguments including input symbol, 
window sizes, weight values, and a data distribution type. The function returns 
an output image. There are two pathnames: one for the filter program that uses 
hypercube for data processing, and the other filter program that runs in the host 
system alone. The quoted strings are the prompt messages. A help message 
describing the function can be provided as well in the function dictionary. 


38 HOST SYSTEM MONITOR 


SECTION 3 


function fllter( 

input "In", STRING 
input "Box width MNT 
input "Box height ",INT 
input "Wgts",INT 
input "Loadtype", STRING) 
returns "Out" STRING 
help "Does a box filter with the given weights" 
pathname "/ufs/cipe/appl/cp/cpfilter” uses hypercube 
"/ufs/cipe/appl/cp/filter" uses host 


An example procedure description is given below. This particular procedure, 
which clears a display screen, does not require any input arguments. 

procedure cleardisplayO 

pathname "/ufs/cipe/appl/cp/cleardisplay" uses host 


When a function is activated by a user in the iconic interface mode, Cipetool 
figures out a proper icon size based on the number of parameters, and displays 
the function icon with prompt messages for the parameters. In the Cli mode, a 
command line is parsed and verified for the number of arguments and their data 
types. The function dictionary file will be improved so that an application pro- 
grammer may not have to deal with user interface modes. 

3.2. DATA MANAGEMENT 

In an image processing environment, frequently, a sequence of functions is 
applied to a data set to remove systematic noises and to enhance the data. It is 
common practice in image processing to apply a function to a data set, save the 
result to a file, retrieve the file for the next function, and so on until the data 
set has been completely processed. Such a scenario is extremely time consum- 
ing when there is more than one system involved for data processing and each 
system requires downloading and uploading of data for each function. 

In order to achieve efficient data processing with minimized file I/O and host- 
concurrent system data traffic, a data sharing mechanism among application 
functions is devised via a cross-referable data management scheme among host 
monitor, concurrent system monitor, and application functions. In a conven- 
tional image processing system, a data set is stored in a file and a file name is 
used as a reference to a data set. However, in an interactive image processing 
environment with one or more concurrent systems, a file system is not an ade- 
quate way of referring to data sets since a data set may reside in more than one 
system or may be distributed among several systems. Therefore, CIPE employs 
a symbol-oriented data management system, where a data set is represented by 
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a symbol structure. 

3.2.1. Symbol structure 

The symbol structure is designed so that a data set can be a subset of an exist- 
ing file, of another symbol, or a set of assigned values. A three-dimensional 
data set is assumed to incorporate scalar, vector, image, and multi-spectral data. 
Also, all data types are allowed and data can be stored in a file, in the host 
memory, and/or in the concurrent system’s memory. The current symbol struc- 
ture assumes that a concurrent system has multiple nodes and local memory 
like a hypercube. The symbol structure contains the following four types of 
information. 

Data Location - Data location is indicated by a file name if a data set is 
in the file, a loadmap pointer if it is in the concurrent system, and/or a 
memory location if it is in the host system memory. When a data set is in 
more than one location, the data in the most proper location will be 
accessed depending on the requested function. 

Size field - The data size is described in three-dimensional terms: number 
of lines, samples, and bands. When the data is a subset of an existing file, 
starting locations are included for each dimension. 

Data type - Data types are described as char, short, int, float, and dou- 
ble. The combination of the data size and the data type allows the proper 
memory allocation for each symbol. 

Data Distribution - When data are distributed among nodes in a con- 
current system, a map describing the distribution is composed and attached 
to the symbol structure. The loadmap is discussed in more detail in Sec- 
tion 5.1.2. 

3.2.2. Symbol Assignment 

A symbol can be assigned a whole set or a subset of an existing file, the output 
of a function, a subset of an existing symbol, or a set of immediate values. 
When a user assigns a value to an existing symbol, CIPE warns the user and 
the symbol is overwritten if the user ignores the warning. 

When a symbol is to be assigned a file or subset of a file, a file name and area 
parameters are specified for a symbol. The symbol name is checked for redun- 
dancy, when the name has not been used before, the symbol is created and its 
information is copied from the header file. The file name and its relative area 
that the symbol represents are associated in the symbol structure. The data are 
not read into a requested system, host memory, or a concurrent system, until a 
process is requested for the symbol, thus minimizing unnecessary data storage 
allocation. 
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read A from file_name # A is a whole file 

read B from file_name(sb,nb,sl,nl,ss,ns) # B is a subset of a file 

When a symbol is assigned to the result of a function applied to an existing 
symbol, the symbol structure is filled in by the applied function based on the 
the input symbol information. For example, the output of a contrast stretch 
function will have data size equal to the input while the output of a zoom func- 
tion will have a zoomed down/up size of input. The memory area for the output 
result may be allocated in the host system memory or in the concurrent system 
memory. The details of output symbol memory allocation for the hypercube 
application program is described in Section 5.1.2. 

A user can assign a constant, a vector, or an array of values to a symbol using 
proper syntax as shown in the example below. 


A=4 

A= {1,2,3, 4} 

A= { { 1,2,3 } , { 2,3,4 } , { 3,4,5 } } 

The parsed values are stored in the host system memory and their location is 
stored in the data location field of a symbol. When a symbol is created and the 
data to be stored in it is a subset of the data in an existing symbol, the data 
parameters may be expressed in relation to the existing symbol. If a symbol 
represented by "A" is to be read from a file with a starting line of 100, a start- 
ing sample of 100, 256 total lines, and 256 total samples, it may be shown by: 

read A from "girl.bw"(100, 100,256, 256) 

A symbol "B" may be said to be the subset of the data in "A" with a starting 
line of 100, a starting sample of 100, 100 total lines, and 100 total samples, all 
by: 


B = A(100,100,100,100) 

The data in B has been expressed in relation to the data in A but B’s symbol 
structure will store the data parameters as if B had been assigned data by: 

, read B from "girl.bw"(200,200,100,100) 


3.2.3. Symbol Table Manipulation 

The symbols are managed through a symbol table. The symbol table is a one- 
dimensional array which contains pointers to the symbol structures. When a 
symbol is created, its structure pointer is added to the symbol table; when a 
symbol is deleted, its structure pointer is deleted from the symbol table and the 
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table is updated. The host monitor provides three symbol manipulation func- 
tions for users and application programs to access the symbol table. 

create_symbol - When a user assigns (a) value(s) to a symbol and/or 
reads a file’s content to a symbol, the symbol is created by CIPE inter- 
nally. In Cli mode, the output symbol of an activated function is created 
by CIPE automatically. CIPE also allows an application program to create 
a symbol. In general, an application program receives symbol names for 
input and output where input symbol names refer to existing data sets, and 
output symbol names refer to data sets that will be produced by the appli- 
cation program. In case of menu mode, the application program receives 
the symbol name from a user for each output data set and it must create 
the symbol by calling the create_symbol function with the user-defined 
symbol name. The create_symbol function creates the symbol entry in the 
symbol table, allocates a symbol structure, and returns the pointer to it. 
Each field in the symbol structure must be initialized by the application 
program for proper size and data type. 

get_symbol - Information of a symbol can be retrieved using a symbol 
name. The symbol table is searched for a given symbol name and the 
corresponding pointer to the symbol structure is returned. Using the 
pointer and macro definition of each field of the symbol structure (defined 
in symbol.h), an application program can access the relevant symbol infor- 
mation. For example, in order to access the number of lines of a symbol 
A, program statements, 

a=cipe_get_symbol(A); 

ns=CIPENS(a); 

are required where a is declared as a pointer to a symbol structure. 

delete_symbol - A symbol in CIPE can only be deleted by a user, and 
should be done when a user determines that the symbol is no longer in 
use. When CIPE receives the symbol deletion command, it checks the data 
distribution status of the symbol and deletes the symbol from all coproces- 
sors who have any portion of the symbol prior to deleting the symbol 
from the host monitor. For example, when a user wants to delete a sym- 
bol A, the host monitor checks the load type of the symbol A and if the 
load type is not none (the data is distributed in the hypercube), the host 
monitor sends a delete_symbol command to the hypercube monitor prior 
to deleting the symbol from the host monitor. 

3.3. FILE MANAGEMENT 

The main purpose of file management is to isolate a programming environment 
from the operating system and executive-specific file formats so that application 
programs are unaffected by changes in the operating system and/or file formats. 
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The disadvantages of executive file management are the added layers of 
indirection, non-standard (executive dependent) programming, and the require- 
ment of learning an extra set of file I/O routine formats. The CIPE file 
management tries to avoid these problems by maintaining standard C language 
I/O function call formats as much as possible and minimizing the indirection. 
More general purpose data file formats are also devised to be compatible with 
other executive environments. 

3.3.1. Header File Structure 

Most executives employ their own file structures using peculiar label formats 
which require a label conversion/removal process for other programs to access 
the data. For very large data files (50 Mbytes or more), the label conversion 
process becomes not only time consuming, but also unfeasible due to limited 
disk space. Several file structures and header file contents have been evaluated 
and discussed. 

Three major file management schemes were proposed: database utilization for 
all data files, a separate header file for each data file, and a structured labeling 
within each file. Since CIPE is designed to demonstrate the computational 
power of concurrent systems in a generic image processing environment, the 
operation-dependent labeling and database ideas were rejected. In order to 
share data sets produced by various executives without the label conversion 
process, CIPE employs a header file separated from the data file. This section 
describes the header file design and file I/O routines. 

The header file is designed to be a variable length file which can be edited and 
displayed using standard edit and type operating system commands, e.g. vi and 
cat The header consists of systematic information, data- set- specific information, 
and application-dependent information. The systematic information includes an 
executive indicator, the offset where the data starts in the file, the data size, and 
the data type. The data-specific information includes starting and ending 
wavelengths for multi-spectral data. Other information that may be required for 
a particular application can be stored in the header file. However, the general- 
ized CIPE header processor will not process application-dependent information. 

Executive Indicator - The executive indicator field contains the name of 
the executive for which the file was produced. For example, a file gen- 
erated by CIPE will have "CIPE" as an executive indicator while a file 
generated by the VICAR (MIPLVJPL) will have "VICAR" instead. The 
indicator field is implemented so that the origin of a file can be preserved 
as well as so that a proper label processor can be activated if the label 
information should be extracted. 

Offset - The offset field contains an integer which indicates where the 
actual data starts in the data file. This field is implemented so that CIPE 
can handle data sets with various types of label information. When CIPE 
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opens a file, it skips the offset number of bytes so that the file index 
points to the beginning of the data area. The offset field is always zero 
for the files that are generated by CIPE. 

Data size - The data set size is described by the number of bands, 
number of lines, and the number of samples in a line in order to incor- 
porate three-dimensional data. A scalar value is described as a three- 
dimensional data set with one band, one line, and one sample. Similarly, a 
two-dimensional image is described as three-dimensional data with one 
band. Three-dimensional data sets are stored in a band interleaved fashion 
where a line from each band is concatenated to form a record in a file. 

Datatype - The type of a data set is expressed as byte, short, int, float, 
or double. The type information is used for determining data size, for 
checking arithmetic operation compatibility, and for data conversion. 

Others - Besides the systematic and general description of a data set, 
there can be data-set-related information which may or may not apply for 
a given application. Such information is an optional part of the header. 
Currently, the starting and ending wavelength fields are implemented in 
the CIPE file header for multispectral data sets. 

The following example header file shows that this is a CIPE header for a data 
file "aisa" which contains a 256 byte label, for a three-dimensional multispec- 
tral data set of size 200 by 28 by 32. The data type is byte type which ranges 
between 0 and 255. 

aisa.hdr 

CIPE 

offset = 256 
number of lines = 200 
number of samples = 28 
number of bands = 32 
type = byte 


3.3.2. CIPE File I/O 

The’ objective of CIPE’s file I/O functions is to isolate the programming 
environment from file structure specifics. CIPE file manipulation consists of an 
external level with which the programmer interfaces, and an internal level that 
CIPE uses to resolve file structure-dependent procedures. 

For external file I/O CIPE provides a file read function (cipe_read_from_file) 
which reads header file information into a symbol structure and reads the data 
into the system memory. A user provides a symbol name and file name along 
with the area of interest. This function activates the CIPE internal file open 
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function to open the header file and data file, and the read function to read the 
data. 

CIPE also provides a file write function (cipe_write_to_file) which writes data 
associated with a given symbol into a file. This function gathers the data from 
the hypercube when the data is distributed among the hypercube nodes and 
composes a header structure. It activates the CIPE internal file create function 
to create a header file and data file, and the CIPE internal write function to 
write the data to the data file. 

The CIPE internal file I/O consists of file open/create, header file read/write, 
and data file read/write functions. The file create function (cipe_create) creates 
a data file using a specified file name and also creates a header file. The 
header file name is composed by concatenating ".hdr" to the data file name. 
The file open function (cipe_open) opens a specified data file and the 
corresponding header file. This function seeks the actual data starting position 
in the data file using the offset information of the header file. 

CIPE provides a header file read (cipe g et image header 1 ) function which 
parses the header file information and constructs an image header structure, and 
a header file write (cipe_put_image_header) function which writes the header 
structure content out to the header file. The read/write/close functions call 
operating system-provided functions. 

3.4. CONCURRENT SYSTEM INTERFACE 

CIPE is designed so that it can be applied as a testbed for various types of con- 
current systems. The concurrent system testbed requires a unique programming 
environment which allows a programmer to access function level routines that 
are shielded from architectural complexities while each function is being exe- 
cuted by a specific concurrent architecture using its full potential. Such a pro- 
gramming environment was approached by implementing a concurrent system 
interface mechanism between a host system and a concurrent system. 

Currently, an 8-node JPL/Caltech Mark in hypercube system and 48 by 48 
NCR Geometric/ Arithmetic Parallel Processor (GAPP) system are implemented 
in CIPE. A concurrent system is activated by a user command (set coprocessor 
to GAPP/CUBE) or a menu selection. The activated concurrent system dynam- 
ically alters the CIPE execution path by loading the corresponding set of 
modules. A concurrent system may be activated at a given time and may be 
released and reaccessed within a CIPE session. 

The hypercube-related executive software is divided into two parts: the host 
resident part, and the hypercube resident part The host resident part of the 
software interfaces with the rest of the executive via standard subroutine calls 
and interacts with the hypercube resident part via a set of predefined com- 
mands. The hypercube resident part is called the hypercube monitor which 
waits for a command from the host process as a slave process. The host 
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resident pan of the hypercube software is discussed here with respect to com- 
mand protocol, data distribution, and application program execution. 

3.4.1. Hypercube Command Protocol 

The host system monitor and the hypercube monitor have a master and slave 
relationship. The host monitor issues a command and the hypercube monitor 
performs the command. The common program environment for generic image 
processing applications is investigated to design a set of relevant commands 
and their execution protocols. Within CIPE, a hypercube application program 
is viewed as a routine that performs a specific data processing function on 
existing data sets. A typical scenario that takes place in the host system moni- 
tor when a hypercube application program is activated is illustrated below. 

Prepare input and output data sets 

(1) create the input symbols in hypercube, 

(2) compose and download the load maps for the input symbols, 

(3) download the data according to the load maps, 

(4) create the output symbols in the host, 

(5) create the output symbols in the hypercube, 

(6) compose and download the load maps for the output symbols. 

Execute the function 

(1) download the function module, 

(2) execute the function, 

(3) wait till execution is completed. 

In order to perform interactive hypercube program execution with automatic 
data preparation, CIPE uses eleven commands to communicate with the hyper- 
cube monitor with respect to symbol management, data I/O, and program exe- 
cution. The commands are sent from the host to the hypercube with an optional 
acknowledgment request. When the request is sent, the hypercube sends back 
an acknowledgment of whether the request was granted or not. Once the com- 
mand is granted, required information for the individual command is passed to 
the hypercube monitor according to the predefined sequence. 

For symbol management, the host executive and the hypercube manage data 
using a symbol table, as discussed in Section 3.2. The hypercube executive 
receives a command for symbol creation (CREATE_SYMBOL) and deletion 
from the host executive (DELETE_SYMBOL) for the symbols whose data are 
provided and/or manipulated by the host. 

The data are distributed to the hypercube nodes after a specific load map is 
written to the hypercube (READ_LOADMAP, READ_DATA). The load map 
describes the data area that each node will receive and is determined by the 
application function. When the data are read back from the hypercube, the load 
map directs the way the data should be assembled (WRITE_LOADMAP, 
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WRITE_DATA). When the data are already present in the hypercube, but need 
to be distributed differently, a data redistribution request (REDIST_DATA) 
may be issued. 

To manage programs CIPE employs a concept called incremental program load- 
ing, where an application function is loaded for execution dynamically. To sup- 
port the dynamic program execution, CIPE sends a command to load an execut- 
able module (LOAD_MODULE) and a command to execute the module 
(EXECUTE_MODULE). A set of built-in functions are also provided and are 
resident in the hypercube during a CIPE session. The built-in functions can be 
activated using the EXECUTE_BUILTIN command. 

When a user wishes to terminate a CIPE session or to change the coprocessor 
from hypercube to another processor, CIPE sends the EXIT command to the 
hypercube monitor. The hypercube may be reaccessed by the coprocessor selec- 
tion command. 

3.4.2. Application Program Management 

As mentioned above, an application program for a hypercube coprocessor con- 
sists of a host resident part and a hypercube resident part. When an application 
function is activated in CIPE, the host system monitor loads the host resident 
application program module into the preassigned program area and executes the 
program. The host resident program loads the corresponding hypercube pro- 
gram to the hypercube (incremental loading by the hypercube resident monitor) 
after the data to be processed are properly distributed in the hypercube. The 
incremental loading of an application program is made possible by linking the 
program with CIPE to resolve all of the global references. More details on 
incremental loading are available in Section 4.3, and a Unix manual on cc. 

3.4 J. Hypercube Data Distribution 

The image processing environment involves large volumes of data. Utilization 
of a hypercube system with many nodes significantly enhances the computation 
by processing the data concurrently. However, large data volume manipulation 
is somewhat complicated since the local memory architecture does not allow 
direct data sharing among nodes, and the data must be transferred via intercon- 
necting channels. 

In order to minimize the application programmer’s effort in data manipulation, 
and to allow a very flexible data distribution scheme, a load map structure is 
composed where a programmer can specify an exact area in a given data set for 
each node. A three-dimensional data set is assumed and a subarea is described 
by starting and ending points in each dimension (line, sample, and band). 

CIPE also provides a set of standard load maps for the frequently applied data 
distribution schemes. The currently supported standard distribution types are a 
broadcast distribution (BCAST_DIST), a horizontal distribution 
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(HORIZ_DIST), a vertical distribution (VERT_DIST), and a grid distribution 
(GRID_DIST). An application programmer simply requests a proper distribu- 
tion type, and the load map is automatically composed. 

The data can be redistributed from one standard distribution to another standard 
distribution without involving the host data download, except to BCAST_DIST. 
Data distributions other than the standard distribution types are considered to be 
customized data distributions (CUSTOM_DIST) and require a user-composed 
load map for each node. The customized data distribution cannot take advan- 
tage of hypercube internal data redistribution. The actual data distribution and 
redistribution are discussed in more detail in Section 4.2.3. 

3.4.4. Data Distribution in an Application Program 

An application program determines how the data should be distributed and calls 
a data distribution routine (cipe_write_data) with a symbol name and a distri- 
bution type. When the requested distribution type is one of the standard types, 
CIPE calls a load map composition routine (cipe_compose_loadmap). Other- 
wise, it assumes the load map is composed correctly by the application pro- 
grammer. Then, CIPE checks to see if the data has been downloaded to the 
hypercube previously. If the data have not been downloaded, the data will be 
downloaded according to the load map. 

If the data have been downloaded previously, there are three possible distribu- 
tion cases: (1) the data distribution is same as requested - no need to download 
again; (2) the new distribution type is compatible with the old type (i.e. one of 
standard types) - call redistribution routine (cipe_redist_data) with old load 
map and new load map information; and (3) the new distribution type is not 
compatible with the old type - delete the existing symbol from the hypercube 
and recreate the symbol using the new data distribution load map. In the last 
case the data exists only in the hypercube; the data will be read back to the 
host prior to deletion. 
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4. HYPERCUBE RESIDENT MONITOR 

A JPL/Caltech MARKHIfp hypercube is employed as a concurrent coprocessor 
for CIPE. Each node is equipped with 4 Mbyte of memory, a Weitek floating 
point processor board, a Motorola 68020 I/O processor, and a Motorola 
68020/68881 data processor. The implementation details of CIPE with regard to 
the hypercube are specific to the MARK Ill/CrOS hypercube, but the basic con- 
cept associated with utilization of a multi-node interconnection topology, local- 
ized memory system, and multiple programming capacity are shared among all 
MIMD systems. Therefore, the monitor design can be easily generalized to 
other MIMD systems. 

The localized memory configuration of a hypercube system allows a very high 
level of concurrency, since a large number of nodes can be connected without 
creating a memory access bottleneck. However, three problems arise: distribu- 
tion of data among multiple nodes is significantly more complicated; data 
transfer between a host system and a hypercube system performed through a 
single hypercube node, node 0, creates a bottleneck; and the memory is shared 
by program and data, one affecting the other for the limited memory space. All 
of these are serious limitations for image processing applications where large 
data sets are commonplace. 

To aid in distributing data to the hypercube, CIPE supports a set of standard 
data distributions and an easy-to-compose data load map structure for custom- 
ized data distributions. These significantly simplify the programming effort 
required in hypercube data manipulation. 

CIPE employs a global data management scheme to permit data sharing among 
successive application programs which reduces the data transfer between the 
host and the hypercube. Data can be redistributed from some distribution types 
to others within the hypercube using the hypercube interconnection topology. 
Redistributing data within the cube reduces data traffic between the host and 
the hypercube, significantly, by allowing data to be shared among successive 
application programs with different data distribution requirements. Near-term 
enhancements to the hypercube include concurrent I/O capabilities between the 
host and multiple nodes of the hypercube. This enhancement should 
significandy reduce the data transfer bottleneck. 

A specialized program management method, incremental loading, is devised for 
efficient hypercube memory utilization for program and data. When an entire 
data set cannot be present in the hypercube at one time, another level of data 
distribution difficulty is added, and the programming is significandy compli- 
cated. Moreover, only the activated function module is required to be present 
in the hypercube node for data processing. Therefore, a trade-off has been 
made between the program area and data area. By loading only an activated 
function module to a preallocated program area, the most memory may be used 
for data. 
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The hypercube monitor performs these data and program management functions 
upon the host system monitor’s command. There are eleven commands includ- 
ing seven data management related commands, three program management 
related commands, and one termination command. In this section, the execu- 
tion of these commands is examined in detail. 

4.1. INTERFACE TO HOST EXECUTIVE 

When a CIPE user initializes the hypercube as the coprocessor of choice, the 
hypercube is reset and the hypercube monitor software is downloaded to the 
cube. Each node of the hypercube has an identical copy of the monitor and 
this monitor will remain resident in each node of the hypercube throughout the 
use of the hypercube as a coprocessor. The host and hypercube interact as a 
master and slave where the hypercube monitor waits to receive a command 
from the host, acknowledges its receipt, executes it, and waits for the next com- 
mand. 

The monitor interfaces to the host executive providing for the execution of 
eleven commands as mentioned in Section 3.4. The commands are for program 
and data management including create_symbol and delete_symbol, for symbol 
management, read_load_map, read_data, write_load_map, write_data, and 
redist_data for data distribution, and load_module, execute_module and 
execute_bui!tin for program management. For each received command, the 
hypercube monitor and the host monitor follow predetermined communication 
steps to receive/transfer necessary information for the command execution. An 
execution sequence is described below, using a create .symbol command as an 
example. 

Host Monitor Hypercube Monitor 

1. Send symbol name 1. Receive a symbol name. 

2. Wait for acknowledgment 2. Check if the symbol exists already. 

If so, then send error 

acknowledgment (NACK) 

and go back to wait; 

otherwise, send acknowledgment (ACK). 

Create the symbol entry in the 

symbol table. 

3. If NACK abort the command 3. Receive the data size and allocate the 

data area; else, send data size. 


Create_symbol Execution Sequence 
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4.2. DATA MANAGEMENT 

A data set is distributed among nodes in the hypercube for processing. Each 
node may have the entire data set or a subarea of the data set according to the 
processing need. The data set distribution information is composed by the host 
monitor for each node and passed down to the hypercube monitor prior to 
actual data transfer. A data set mentioned in this Section refers to a portion of 
data which resides in a given node. 

Similar to the data management of the host monitor discussed in Section 3.2, a 
data set in the hypercube monitor is represented as a symbol which is associ- 
ated with an attribute structure describing its name, data type, and load map 
(distribution scheme). A data set is accessed by its symbol name by application 
programs. The hypercube monitor employs a symbol management scheme very 
similar to the host monitor. 

4.2.1. Symbol Structure 

The symbol structure employed by the hypercube monitor receives the symbol 
information through a create_symbol command for the name and datatype, and 
through a read_load_map command for the loadtype and data distribution 
scheme. The symbol structure contains name, datatype, and a load map field. 
The load map field contains loadtype, location, and size field. The symbol 
structure declaration can be found in Appendix I under elt_symbol.h. 

Data type - An element within a symbol is described for its type as char, 
short, int, float, and double. The combination of the data size and the 
data type allows a proper memory allocation for each symbol. 

Load type - Data distribution type is described as BCAST_DIST, 
HORIZ.DIST, GRID.DIST, VERT_DIST, CUSTOM_DIST (see Sec- 
tion 3.4 for the type definition). The loadtype information combined with 
the load map allows the data redistribution within the hypercube. 

Load map - The load map describes the absolute data location of a sym- 
bol in a node in reference to the whole data set in three-dimensional 
terms. The starting location and its size for each dimension are expressed 
in lines, samples, and bands. 

Data - Data area is allocated separately from the symbol attribute struc- 
ture, and its address is stored in the data location field of the symbol struc- 
ture. 

4.2.2. Symbol Table 

The symbols are managed through a symbol table. The symbol table is a one- 
dimensional array which contains the pointers to symbol structures. When a 
symbol is created, its structure pointer is added to the symbol table. When a 
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symbol is deleted, its structure pointer is deleted from the symbol table and the 
table is updated. The hypercube monitor provides three symbol manipulation 
functions for hypercube module application programs to access the symbol 
table. 

create_symbol - A symbol can be created as a global symbol or as a local 
symbol. A global symbol is created when the host monitor sends a 
create_symbol command. The global symbols are employed for data shar- 
ing among application programs. The global symbol data is managed by 
the hypercube monitor and only application programs can access them. A 
local symbol is created by an application program and is known only to 
the application program. Local symbols are deleted by the monitor upon 
the completion of the hypercube resident application program which 
created them. When a local symbol is created, the hypercube monitor allo- 
cates a symbol structure, initializes each field with default values, and 
returns the pointer to the allocated area. Each field in the symbol structure 
must be updated by the application program for proper size and data type. 

get_symbol - Symbol information is retrieved using a symbol name. The 
symbol table is searched for a given symbol name and the corresponding 
pointer to the symbol structure is returned. Using the pointer and macro 
definition of each field of the symbol structure (defined in elt_symbol.h), 
an application program can access the relevant symbol information. For 
example, in order to access the number of lines of a global symbol A, pro- 
gram statements 

a=get_symbol(A, GLOBAL); 
ns=NS(a); 

are required. 

delete_symbol - a symbol entry created by an application program may be 
deleted by an application program using the delete_symbol function. 
Symbols created by the host monitor are deleted by the hypercube monitor 
when the delete_symbol command is received. 

4.2.3. Data Distribution/Redistribution 

Data is distributed through the use of the monitor’s READ_DATA and 
WRITE_DATA commands. Before data may be read, a symbol must exist and 
a load map must have been read to know the data decomposition type and the 
specific load map parameters. Data is read into the cube in one of five distri- 
bution types: a BCAST_DIST, which sends the entire data set to each node; a 
HORIZ_DIST, which breaks the data into horizontal regions; a GRID_DIST, 
which breaks the data into a grid; a VERTJDIST, which decomposes the data 
into vertical regions; or a CUSTOM_DIST, which permits the decomposition of 
data in any manner that may be specified by six parameters, one each for the 
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starting point in the x,y,and z directions, and one each for the duration of pixels 
in each direction. 

CIPE images are stored line by line. This means that a two-dimensional image 
with dimensions 512 x 512 pixels is stored, line 1 first, with samples 1 through 
512, then line 2, samples 1 through 512, continuing to line 512. The host com- 
puter communicates data and images to the hypercube using commands pro- 
vided by the Crystalline Operating System (CrOS). The hypercube command, 
bcastcp (broadcast from the control processor), allows a user to specify the 
address of a buffer and the number of bytes to be sent from that buffer. The 
specified number of bytes is sent from the beginning of the buffer to each node, 
so that each node has exactly the same data. This is the way a BCAST_DIST 
is achieved. Another hypercube command, mloadcp, allows the user to specify 
the address of a buffer and a load map of how many bytes are to go from that 
buffer to each node. The command starts at the beginning of the buffer 
specified and sends distinct but contiguous blocks of data to the nodes, begin- 
ning with node 0. In this manner an image ends up in the nodes in a horizon- 
tal decomposition (Figure 4.1), and no two nodes receive the same data. 



Figure 4.1 Horizontal Decomposition 


Neither a GRID_DIST, VERT_DIST, or CUSTOM_DIST are achieved simply 
by the use of a CrOS communication call. A grid or vertical decomposition 
begins by being downloaded into a horizontal distribution. The data is then 
moved within the cube to create a grid or vertical decomposition. The same 
result could be achieved by rearranging the data in the host and then using the 
same hypercube command as for a horizontal distribution, mloadcp, to send the 
data to the cube. Such an implementation does not allow the user to take 
advantage of the additional processing capability of the hypercube. The bold 
lines in the following diagram outline the areas of an image held by each node 
in a horizontal distribution. The patterned regions show the data regions 
desired to form a grid decomposition (Figure 4.2). To determine how to 
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Figure 4.2 Horizontal Decomposition and Desired Grid Decomposition 

manipulate the data from one decomposition to another, it is important to 
observe the node connectivity within the cube, and the possible data paths 
between nodes for data exchange (Figure 4.3). 








Figure 4.3 Hypercube Node Connectivity 

Figure 4.3 shows the connectivity of the nodes and the data each node is hold- 
ing. In' a four node hypercube only nodes 1 and 2, and nodes 0 and 3 lack a 
direct connection. In this example the data exchange to achieve a grid decom- 
position is simple. Nodes 0 and 1 in a horizontal decomposition have all the 
data necessary to create two regions of a grid decomposition. The same is true 
for nodes 2 and 3. Moreover nodes 0 and 1, and nodes 2 and 3 are directly 
connected. All that is necessary is for each node to determine what data it 
needs to keep, what data it needs to exchange, and to then utilize the appropri- 
ate CrOS command to exchange the data with the appropriate neighbor. 
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Figure 4.4 Data in Node O 

The beginning of Node 0’s data as it is stored in memory is pictured in Figure 
4.4. The task of separating the data to be retained and the data to be 
exchanged requires that an additional buffer half the size of the current buffer 
be created. Each node knows the length of its lines from its load map. Node 0 
will retain the first half of its first line, la, in the beginning of the original 
buffer. The second half of its first line, lb, will be copied to the beginning of 
the new buffer. The area in memory where lb was stored in the original buffer 
will not be erased, but other data will be written on top of it. The first half of 
the second line, 2a, will be appended to la in the original buffer. The second 
half of the second line, 2b, will be appended to lb in the new buffer. The con- 
tents of the new and original data buffers, at this time, are pictured below (Fig- 
ure 4.5). 
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Figure 4.5 Node 0 and Node 1 Buffer Contents 

Two pointers are required in the original buffer: one to maintain the end of the 
contents of the new data being compacted there, and one to maintain what data 
is now being moved. The process occurs in each node until all the data in the 
original buffer is divided between the two buffers. 

As described earlier, nodes 0 and 1, and nodes 2 and 3, need to exchange data 
to create a grid decomposition, and these nodes are directly connected and 
require no middle node to communicate. No CrOS command allows a user to 
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specify a node with whom to exchange data. A programmer must determine 
what channel connects two nodes and request that an exchange be done on that 
specific channel. The channel connecting two nodes is determined by looking 
at the binary gray code representation of the node numbers and seeing in which 
one digit the two nodes desiring to exchange differ. Node 0 may be 
represented in binary by 000, and node 1 by 001. The units, 2’s, and 4’s digits 
are numbered from right to left beginning with 0. So 000 and 001 differ in one 
digit, the units digit, numbered 0, and therefore communicate along channel 0. 
Similarly node 2, 010, and node 3, Oil, differ in the units digit, and also com- 
municate along channel 0. Therefore, in order for a horizontal distribution to 
become a grid decomposition, all nodes must determine the data they need to 
retain and exchange, and exchange the appropriate data with their neighbor 
along channel 0. (Figure 4.3 has channel numbers between nodes labeled.) It 
may be seen empirically that this process is true for any n-dimension hyper- 
cube. 

To create a vertical distribution from a horizontal distribution requires that data 
be exchanged along successive channels, from 0 through the number of dimen- 
sions of the hypercube. In each case, the nodes determine data to be 
exchanged and retained, divide it up, and exchange on the appropriate channel. 
The process may also be reversed to go from a vertical to a horizontal distribu- 
tion. Other uses of this process to move forward and backward through a hor- 
izontal, grid, or vertical decomposition will be discussed later. 

A CUSTOM_DIST, or a customized distribution, makes full use of its load 
map. An entire image is broadcast to each node in chunks using the CrOS rou- 
tine, bcastcp, discussed earlier. Before each data chunk is sent, a package is 
sent to each node telling it what part of the image to expect. Each node looks 
at its own load map to determine what portion of the incoming data it is sup- 
posed to have. It copies any of the incoming data it needs to its own buffer, 
and then prepares to accept the next package of data information and data. The 
size of the data chunks being sent is now rather arbitrary. In the future, the 
size of the data chunks sent will be determined by the available memory in the 
nodes. 

In addition to providing for the initial distribution of data, CIPE provides some 
capabilities for redistributing data from one decomposition to another. These 
capabilities help to achieve one of the goals of CIPE, to minimize data I/O and 
thus improve the overall efficiency of the image processing being done. 
Different image processing applications may prefer data in one decomposition 
over another. If CIPE is able to redistribute data within the hypercube without 
the need to download data again it is able to save time. It is not always possi- 
ble to manipulate data within the hypercube from one decomposition to 
another. The following diagram illustrates what redistribution cases are possi- 
ble (Figure 4.6). If there is a path created by the directional arrows between 
two distribution cases that have no direct arrow between them, as in the 
HORIZ _DIST to GRID_DIST to VERT_DIST, that redistribution is possible 
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as well, as in HORIZ.DIST to VERT_DIST. 



Moving HORIZ.DIST to GRID.DIST, and GRID.DIST to VERT_DIST, is 
achieved exactly as it is for an initial grid or vertical distribution as described 
before. Moving from a VERT_DIST to a GRID_DIST, and from a 
GRID_DIST to a HORIZ_DIST, is achieved, similarly, by reversing the pro- 
cess. Data is exchanged along channel n where n is the number of dimensions 
of the hypercube. A node now has its own buffer and another it received from 
a neighboring node. Then two buffers are pieced together, one line from each 
of two buffers, to create one line of a new buffer. This process continues along 
each channel decreasingly to channel 0. The process may stop at any channel 
to create some variety of a grid decomposition. Depending on the dimension 
of the hypercube, more than one kind of a grid distribution may be formed 
between a horizontal and vertical distribution. What CIPE calls a GRID_DIST 
is one data exchange along channel 0 beyond a HORIZ_DIST. Redistributing 
data from a BCAST_DIST to any other distribution is achieved similar to the 
way a CUSTOM_DIST is achieved. All nodes have the data for an entire 
image, and they know the dimensions of that image. The nodes receive their 
new load map indicating what data they should now have, and copy the 
appropriate data to the beginning of their buffer space, overwriting the previous 
data. 

CIPE’s methods for distributing and redistributing data for the hypercube have 
been developed to use existing CrOS routines to maintain compatibility with 
others using the Caltech/JPL Mark HI hypercube, and to avoid the need to 
exchange data between two nodes that are not directly connected. If two nodes 
needing to exchange data have no direct connection, extra memory and process- 
ing time is needed in the nodes to maintain their own data as well as permit 
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data to pass through enroute to another node. Using extra memory for this pur- 
pose places greater limitations on our program and/or data size, thus diminish- 
ing the effectiveness of CIPE. One problem with the method of distributing and 
redistributing data CIPE uses is that in every decomposition there is some place 
in which contiguous pieces of an image are stored in non-adjacent nodes. In the 
following diagram the middle of the image, held by nodes 1 and 2, is patterned 
(Figure 4.7). 



Figure 4.7 Node Ownership of Image Sections 

But as the data is held in the nodes the patterned region is in two non- 
neighboring nodes (Figure 4.8). 


Node 0 







Node 3 


Figure 4.8 Contiguous Data in Non-adjacent Hypercube Nodes 
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This is a real weakness because many image processing applications will 
require overlapping data regions. Since no CrOS command provides for down- 
loading data so that data regions overlap, it would be convenient to be able to 
download data into one of CIPE’s standard distributions and then exchange the 
necessary data so the data regions overlap. Not only would it require exchang- 
ing data with a non-neighboring node and the complications that have been 
explained which that involves, but it also requires a tricky routing algorithm 
which has not yet been determined. 

4.3. PROGRAM MANAGEMENT 

The hypercube monitor provides 100 kbyte of memory area for an application 
program under the name of Progarea. Hypercube modules for each application 
program are linked with the hypercube monitor so that each is located precisely 
in the Progarea using an incremental loading facility of the UNIX linker. The 
linker resolves the external references of each application module and produces 
an executable file. 

Upon receiving a load_module command, the hypercube monitor reads the 
executable file into the Progarea. When the host monitor issues an 
execute_module command, the hypercube monitor jumps to the Progarea and 
starts executing the loaded module. Thus, the incremental loading mechanism 
limits the hypercube resident application module memory usage to 100 kbyte. 
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5. APPLICATION PROGRAMMING WITH CIPE 

The CIPE programming environment pursues an architecture-independent 
environment where a programmer may write an application program without 
concern for architectural specifics. This section presents application program- 
ming with CIPE using the JPL/Caltech Mark HI hypercube as a concurrent sys- 
tem. Without the support of an executive or the use of a concurrent system, an 
application program must perform three functions: user interface, data I/O, and 
data processing. In an application program using a hypercube, the data pro- 
cessing is downloaded to the hypercube system for concurrent processing. In 
this case, a programmer writes two program modules, one for the host and one 
for the hypercube. In the host module, the programmer is responsible for read- 
ing data from a file and distributing it among the hypercube nodes. It is also 
the programmer’s responsibility to receive the data in the hypercube module. 
This process requires a full knowledge of the hypercube architecture and 
operating system. 

CIPE provides simple function calls to support user interfaces, perform file I/O 
and/or data I/O, and various other functions. An overview of a CIPE applica- 
tion program is illustrated in Figure 5.1. The host module consists of three 
parts: the user interface which interacts with the Menu and the Cli modes of 
CIPE; the interaction with the host system monitor to perform input data distri- 
bution, output data load map distribution, and hypercube module activation; and 
finally, interaction with the hypercube module to pass parameters to the 
activated hypercube module and wait for completion of the data processing. 
The hypercube module consists of two parts: the parameter reception and data 
processing. Data is received prior to hypercube program module activation by 
interaction between the host system monitor and the hypercube resident moni- 
tor. The hypercube module accesses the data by interaction with the hypercube 
monitor. 

The design and implementation details of the user interface, host system moni- 
tor functions, and hypercube monitor functions are described in previous sec- 
tions. This section explains how an application programmer can utilize the 
CIPE functions to process data in a concurrent system environment. 

5.1. HOST SYSTEM RESIDENT MODULE 

In CIPE, a host resident application program can be viewed as a subroutine 
dynamically loaded to a fixed location where CIPE is the main program. When 
a user requests a function provided by the application program the main pro- 
gram loads an application program file and activates it by a subroutine call 
mechanism. A set of common program procedures is shared by all of the host 
system resident modules in CIPE. Each module must provide two user inter- 
face modes for user input parameters, input data access and distribution, and 
hypercube module activation and interaction. As illustrated in the host resident 
application program example. Figure 5.2, the host resident module of a filter 
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Figure 5.1 Hypercube Programming in CIPE 
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program consists of four sections: the variable declaration, the user interface, 
the host resident monitor interaction for data distribution and hypercube module 
activation, and input parameter passing to the hypercube module. The exam- 
ples referred to throughout the subsections of 5.1 refer to Figure 5.2. All host 
resident modules must include cipeappl.h to provide the variable and structure 
definitions common to all CIPE applications. 

5.1.1. User Interface 

CIPE can be in one of three user interface modes (menu mode, Cli mode, or 
Cipetool) when an application program is invoked. Since Cipetool translates a 
user’s actions into Cli commands, a CIPE application program must provide 
two user interface modes for user input parameters using provided function 
calls and macro definitions. Future enhancements to CIPE will include a con- 
sistent means for a programmer to provide all three user interfaces, and will 
eliminate the need for function calls. The main difference between the menu 
mode and Cli mode user interfaces is in the user parameter value reception pro- 
cess. 

5.1.1.1. Creation of a Menu Interface 

In menu mode, parameters are received directly from a user and stored in their 
corresponding variables by the use of the Yamm routine def. Interactive error 
checking of parameters is the responsibility of the programmer and is accom- 
plished by the use of the Yamm routine getpar. A programmer may provide 
interactive help messages for each parameter field in a manner similar to the 
error checking. Both def and getpar must be used to create the desired display 
on the input screen and to read the user’s input; getpar must follow def. To 
be able to use the routines def and getpar, an applications programmer must 
first make the declarations: 
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tfifndef lint 

static char sccsid[]= %G%”\ 
tfendif lint 

/* %Xf% version ^cl&c. %G% * / 
^include <stdio.h> 

^include <ctype.h> 
a include <ermo.h> 

^include <cros.h> 

^Include "cipeappl.h" 

cpfikerO 

( 


/„*,»*,*«,,,,«*,*** VARIABLE declaration SECTION **%%*•*****♦♦♦♦**% / 

/* .V/enu Related * f 

struct par am params(4]; 
int param_count; 
int check_filter(); 


/* Symbol Related * / 

cipe_sym_name input,output; 

struct cipe_symbol *sin, *sout, *cipe_get_symbol(); 
int sindex; 


/*— Hypercube Related • / 

int *packets,packet_size; 

int *bu£map_receive, *bufmap_$end; 


/* Application Related * / 

int window [2]; 
char loadtype[2]; 

int i, ok, share, ^weight, *argptr; 


/* Variable Initialization * / 

bufmap_receive = (int * )maUoc( (nproc* l)*slieof( Int)); 
bu£map_send = (Int *)malloc((nproc+l)*$tzeof(lnt)); 
bufmap_send(0] - nproc; 
bufmap_receive(0] = nproc; 

strcpy(Ioadtype,”c'*); 




/mmmmmmmimmm USE* INTERFACE SECTION •••••••••••••••••••••• / 

* 

/* Mem* • / 

if (MENU MODE) { 

paiam_ count = 4; 

def( par ams,0,” input symbol name \ STRING, input, WID,32,LINE, 2, 

REQ.END); 

def(params.l,”output symbol name ’’.STRING, output, WID,32XINE,3, 

REQ.END); 

def(params, 2, "filter window(nlwjisw) \INT, window JNCR.4.WID. 10, 

LINE,4,DUP.2, REQ.END); 

def(params,3, M load type (h/v/g/c) ',STRING,loadtype,WID,10, 

LINE,6, REQ.END); 

if (getpar(params,param - count,check_filter.NOHELP)) return; 
weight = (int ♦)malloc(window(0]*window[l]*slzeof(lnt)); 


Figure 5.2 Spatial Filter Control Processor Program 
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for (i=0: i<wmdow[l]; i-w*) { 

denparams.i, "weight values ",INT,weight+i t 
[NCR.sizeof(int)*window( 1 J.LINE.2, 

ENTRYLINE,3,ENTRYCOL,i* 10,DUP,window( 1], GROUP, 0,REQ, END); 


if (getpariparams,window(l],NOECHK,NOHELP)) return; 


Endjdenu * / 


/* Cli • / 

else { 

sin = ARGPTR(O); 

wmdowfO] = *(Lnt *)ARGDATA(1); 

windowf i] = *(lnt *)ARGDATA(2); 

weight = (Int *)malloc(window[0]*window[t]*sizeof(lnt)); 

argptr = (Int *)ARGDATA(3); 

for (i=0; i<window[0]*wmdow[l]; i-M-) 
weight[i] = argptr[i]; 
strcpy(loadtype,(char *)ARGDATA(4)); 
sout = RESULTP; 

) 

/* End Cli • / 


/ * ******* / 

,*.**,•***** CI p E H0S J RESIDENT monitor interface SECTION ***•***••• / 

******* ********* ****************** 

/* Symbol Retrieved * / 

If (MENU_MODE) ( 

sin = cipe_get_symbol(input); 

ok = cipc_cTeat_symboi(output,&sout,&sindex); 

} 

I* End_Symbol Retrieval * / 

/* Custom _Dist * / 


share = (CIPENL(sin)-Kiproc-l) /nproc; 

if (strcmp(loadtype,"c")=0) { 

if (CCPELOADMAP(sin) = NULL) 

CIPELOADMAP(sin) = 

(struct loadmap *)mailoc(nproc*slzeof (struct loadmap)); 
for (i=0; i<nproc; i-M-) ( 

CIPELOADMAP(sin)(i].ss = 1; 

CIPELOADMAP(sin)(ij.si = i*share - ( window [0] (2)\ 

CIPELOADMAP(sin)(i).sb * 1; 

CIPELOADMAP(sin)[ij.nl * share +window[0]; 

CIPELOADMAP(sin)[i].ns = CIPENS(sin); 

CIPELOADMAP(sin){i].nb = CIPENB(sm); 

) 

/* starting line must be positive value • / 

CIPELOADMAP(sin)(0].sl = i; 

I* The last proc may get little less data • / 

CIPELOADMAP(sm)[npfoc-l ].nl = 

CIPENL(sin)-CIPELOADMAJP(sin)[nproc- 1 ] .sl+1 ; 
ok = cipe_cube_wnte_dau(sia,CUSTOM DIST); 

} 

/* End _Custom Dist * / 

/* StandardJDist • / 

if (strcmp(loadtype, , 'h’ , )=0) ok = cipe_cube_wnte_data(sin,HORIZ_DIST); 
if ( strcmp( load type,' V’)=0) ok = cipe j: u be_ write_data( sin, VERT_ DIST); 
if (strcmp(loadtype, , g M )=0) ok » ci pe_cube_wriLe_data( sin, GRID_ DIST); 
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... cpfilter 

* — End_Standard_Dist * / 

/* — — Output ^Symbol • / 

CIPEDATATYPE(sout) = Cl PE DATATYPES in); 

CIPENS(sout) = CIPENS(sin); 

CIPENUsout) = CIPENUsm); 

CIPENB(sout) = CtPENB(sin); 

CIPENDEM(sout) = CIPENDIM(sin); 

/* LOADTYPE and others * / 


if (strcmp(loadtype,"c")s=rO) ok = cipe_cube_write_loadmap(sout,HORIZ_DIST); 

if (strcmp(ioadtype, M h")==0) ok = cipe_cube_wnte_loadmap(sout,HORIZ_DIST); 

if (scrcmp(loadtype,V , )=0) ok = <npe_cube_writeJoadmap(sout,VERT_DIST); 

if (scrcmp(loadtype, M g")==0) ok = cipe_cube_write_loadmap(sout,GRID_DlST); 

/* EndJDutputJlymbol * / 

/* Load Hypercube-Module * / 

cip^cub^executejnoduleC ’nodefilter )» 
pnntf("nodefilter will be startedW); 

/* End Load Hypercube-Module * / 




hypercube module interface section 

/MMMMMMM 

/* 

packet_size = slzeof(lnt); 

packets = (Int *)maUoc(nproc*packet_size); 


***/ 

**•/ 

•••/ 

Parameters 


* f 


bcastcp(CIPENAME(sin),sizeof (cipe_sym_name)); /•- input symbol 

ok=mdumpcp(packets,packet_size,bufmap_receive); 

If (packets(O) = NOK) 

printf ("symbol %s has not been created VT,CIPENAME(sin)); 


/ 


bcastcp(CIPENAME(sin),sizeof (cipe_sym_name)); /* output symbol * / 

ok=mdumpcp(packets.packet_size,bufmap_recetve); 
if (packets[0] = NOK) 

printf("symbol %s has not been created \n\CIPENAME(sin)); 

ok=bcastcp(window,sizeof(window)); /* — window size * / 

ok=bcastcp(weight,window[0]*window(l]*siieof(lnt)); /* weights 

pnntf("ok=%dV\ok); 

I* End ^Parameters • / 

/* Wait */ 

ok=mdumpcp(packets,packet_size,bufmap_receive); 
printfCfilter has been completed(%d)Nn\ok); 

i* End _W ait * / 


/ 


free(bufmapj’eceive); 
free(bufmap send); 

} 

check_filter<params 4 iumber,value) chcck^flltCT 

struct param *params; 
int number; 

union (int i; double f; char *s;) value; 

( 

int error, whereis; 
error = 0; 
switch(number){ 

case 0: whereis=cipe_get_symbol_index(value.s); 

If (whereis == NO SYMBOL) error = l; 
if (error) printf( M symboi does not exist"); 

break; 
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case 1: whereis^ipe_get_symboljndex(value.s); 

If (where is != NO_S YMBOL) error = 2; 
if (error) printf( ’symbol already exists”); 

break; 

case 2: if (((value.i) % 2) = 0) error * 3; 

if (error) printf(”must be odd number”); 

break; 

} 

if (error != 0) return(-l); 
else return(O); 

} 


struct param pa rams [number _of parameters]; 

int param_count; 

int error _checking_rout_name(); 

int help _r out _nameQ; 

The last two declarations are only required if the programmer cares to provide 
the user with help and input parameter error checking. These declarations may 
be found in the variable declaration section labeled menu related. In addition, 
all parameters to be read interactively from a user must also be defined. Such 
parameters are likely to include references to data sets which are stored as sym- 
bols within CIPE and referenced by a symbol name. For this reason the appli- 
cation program should request symbol names for input and output. These must 
be declared by, 

cipe_sym_name input _symbol_name(s), output _symbol_name(s); 

as shown in the variable declaration section labeled symbol related. All other 
interactively read input should be declared in a manner appropriate for the 
application. In the example application two other such declarations exist, 

int window[2]; 
char loadtype[2]; 

and they appear in the variable declaration section labeled application related 
along with other miscellaneous variables needed by the application. Yamm 
does not have a character type; all characters must be declared as strings with a 
minimum length of two; one byte to store the desired character and one byte 
for the- null terminator that must end strings. The loadtype above is an exam- 
ple of this type of definition. 

With the necessary variable declarations complete, an application programmer 
may proceed to write the menu mode user interface. This begins with an if 
statement to see if the user is in menu mode or Cli mode, followed by an 
assignment to param_count of the number of def statements to be used to read 
input from the user, the corresponding def calls to read the input from the user, 
and a call to getpar to actually create the display screen, and provide help and 
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input error checking. 

if (MENU_MODE) { 

param_count = number _of_def statements ; 
def(params,de/_srmr_nMm,"User prompt” j)aram_type, 
variable name 
def(params,...); 

def(params,umber_of_def_statements-i 

if ( getpar(params,param_count,error_checlcing_rout_name, 
help_rout_name ) ; 

} 

In the above example the parameters associated with def and getpar, which are 
shown, are required. There are additional parameters that may be given to def, 
and predefined constants that should be used to specify parameter types, or the 
absence of error checking or help routine names. The sample program uses 
some of the extensions to the def statement. The first def statement of the sam- 
ple program, 

def(params,0, "input symbol name ", STRING, input, WID ,32, 

LINE, 2, REQ,END); 

reads into the block storage for parameters, params, in the first def statement, 
0, with the prompt, "input symbol name", a variable of type, STRING, into 
the memory location of, input, a value that may take up to the number of 
columns that follow WID, 32, where the prompt will be positioned on the line 
number following LINE, 2. REQ indicates that the value being requested is 
required not optional, and END indicates there are no more parameters or the 
def statement. In the example getpar statement, 

if (getpar(params,param_count,check_fiIter,NOHELP)) return; 

the parameter params points to an array of parameter definition structures; 
param_count, is the number of def statements; the routine to error check the 
parameters is called check_filter (shown at the end of the example program); 
and, NOHELP indicates that no help routine is provided for the parameters. 

An error checking routine must have the same name as it was given as an argu- 
ment to the getpar function, and it must have been declared in the variable 
declaration section as mentioned previously. All error checking routines must 
have three arguments, params, number, value, declared as shown in Figure 
5.3, which was taken from the sample application program. Within the error 
checking routine a switch statement must be set up. The cases of the switch 
statement, 0-n, correspond to the order of the def statements which read in the 
values being checked; the second parameter to the def statement gives its order 
number. Within each case, checking is done as is appropriate for the value 
being checked. In some situations it may be possible to use routines provided 
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check_filter(params, number, value) 
struct param *params; 
int number; 

union {int i; double f; char *s;} value; 

{ 

int error, whereis; 

error = 0; 

switch(number){ 

case 0: whereis=cipe_get_symbol_index(value.s); 
if (whereis == NO_SYMBOL) error = 1; 
if (error) error_print("symbol does not exist"); 
break; 

case 1: whereis=cipe_get_symbolJndex(value.s); 
if (whereis != NO_SYMBOL) error = 2; 
if (error) error_print("symbol already exists"); 
break; 

case 2: if (((value.i) % 2) == 0) error = 3; 

if (error) error_print("must be odd number"); 
break; 

} 

return(error); 

} 


Figure 5.3 Menu Mode Error Checking Routine 

by the executive to assist the programmer in error checking a user’s input. One 
example of such a routine is explained here and others will be explained later 
in this section. The first def statement reads in an input symbol name so the 
error checking routine under case 0 checks for the existence of the symbol in 
the symbol table. It uses the executive routine cipe_get_symbol_index which 
it provides with the symbol name stored in value.s, to see if the symbol exists. 
If it does not, cipe_get_symbol_index will return NO_SYMBOL, and the user 
will be given the error message and left in the same menu on the first line to 
indicate that he/she needs to provide another input symbol. As each parameter 
is filled in, check_filter is called again with its number in the order of the def 
statements stored in number, and the value entered by the user stored in value. 
The assignments to the arguments of an error checking routine and the calling 
of the error checking routine following each user entry are provided by the 
menuing package. The second def statement read in the output symbol name. 
An output symbol should not exist, so check_filter under case 1 again uses 
cipe_get_symboI_mdex, but this time if the symbol is found it gives the user 
an error message to say that the symbol already exists. Case 2 checks to see 
that the values provided for the filter window size were odd. No error check- 
ing is provided for the last def statement which asks for the load type. This 
could be provided by adding a case 3 to the check_filter switch statement. 



70 APPLICATION PROGRAMMING WITH CIPE 


SECTION 5 


Note that each case ends with a break. 

Help may be provided similarly to error checking. The sample program does 
not provide help. To provide help, a help routine would need to be declared in 
the variable declarations, and the help routine name would need to be added to 
the getpar statement as its fourth parameter in place of the NOHELP constant 
that was there previously. In the following getpar a help routine named 
help_filter has been added. 

if (getpar(params,param_count,check_filter,heIp_fiIter)) return; 

Then the routine help_filter must be created. All help routines must have two 
arguments, two of the three required in an error checking routine. A help rou- 
tine has no need to know the value a user may or may not have entered and so 
no value is sent to the help routine. The arguments params and number must 
be declared as they were for the error checking routine. A switch statement 
must be set up with cases for each of the def statements the programmer 
desires to provide help. Within the case statements help messages may be 
printed using printf. Yamm will pack the lines and provide new lines. The 
help routine in Figure 5.4 could be added to the sample application program. 
For further information on an application program’s use of Yamm see the 
Yamm Programmer’s Guide in Appendix G. 

5.1.1.2, Creation of a Cli Interface 

In Cli mode, the user is not prompted for an application function’s input. A Cli 
user is expected to know the functions being used and their input parameters. 
When the user inputs a command to execute an application function, the Cli 
parses the command according to its grammar, identifies it as an application 
function, and looks up the function name in the function dictionary. The func- 
tion dictionary provides information on the number of parameters that should 
have been provided to the function, and whether each is an input or an output 
parameter. The Cli checks for the existence of any symbols which have been 
entered as parameters to the command. If an input symbol does not exist, the 
user is provided with an error message that points to the undefined symbol. If 
an output symbol does exist, the user is also provided with an error message. 
Values entered as parameters are not associated with a symbol so no error 
checking is done for them. The Cli passes each parameter of an application 
function as an argument list of symbol table indices. In order for this to hap- 
pen, input symbols are retrieved for the user, output symbols are created, and 
any values are stored as symbols, each under its own temporary name, along 
with its information on size, type, and values. The Cli command line 

B = fiIter(A^,3,{l,l,U,2^,3^,3},"c’’); 

entered by a user, calls for the execution of a spatial filter function on a data 
set represented by a symbol A, using a 3 by 3 window with weight values 
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help_filter(params, number) 
struct param *params; 
int number; 

{ 

switch (number) { 
case 0: 

printf("A valid input symbol must be associated "); 
printf("with two dimensional image data.'*); 
break; 
case 1: 

printf("A valid output symbol must not already exist. "); 
printf("You may see if it does by using List from the"); 
printf("Symbol Menu."); 
break; 
case 2: 

printfC'Dimensions of the filter window must be ”); 
printf("odd numbers."); 
break; 
case 3: 

printf( "Horizontal, vertical, grid, and customized "); 
printf("decompositions "); 

printf("have been provided. Choose one by typing the "); 
printf("first letter of the word. "); 
break; 

} 

} 


Figure 5.4 Sample Help Routine 


specified in the curly brackets, sent to the cube in a customized decomposition, 
"c". The Cli converts the command line into an argument list which contains 
six symbol indices to symbols containing A, 3, 3, (1,1,1,2,2,2,3,3,3), "c", and 
the resultant symbol B. 

To simplify the access to the argument list, four macros have been designed: 


ARG(n) 

ARGPTR(n) 

ARGDATA(n) 

RESULTP 


symbol table index of the n-th argument 
pntr to symbol table location of n-th argument 
pntr to location of data of n-th argument 
pntr to symbol table for output/resultant symbol 


All the variables a programmer needs to program a Cli interface have already 
been declared to create the menu interface. A programmer needs only to look 
at the variable definitions and their functions to determine which of the four 
macros should be used to assign a value to the variable that represents each of 
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the user input parameters. For example, for any variables declared to be sym- 
bols the macro, ARGPTR(n), should be used to assign a pointer to a symbol 
table location. For variables that only need to be assigned values, the macro, 
ARGDATA(n), may be used. ARGDATA(n) is a pointer to data and will 
need to be prefaced with an if its contents are to be accessed. The output 
symbol variable should be assigned the value of RESULTP which contains a 
pointer to the symbol table entry of the output symbol. The macro definitions 
assume the existence of only one output symbol; for future applications this 
will need to be modified. The lines, 

sin = ARGPTR(O); 

window[0] = *(int *)ARGDATA(1); 

window[l] = *(int *)ARGDATA(2); 

begin by taking the pointer to the symbol table location of the first argument, 0, 
and assigning it to sin, which is of type cipe_symbol. The second line takes 
the contents of the data location of the second argument in the argument list, 1, 
and assigns it to window[0]. The third line takes the contents of the data loca- 
tion of the third argument, 2, and assigns it to window[l]. See the user inter- 
face section labeled Cli for a complete Cli interface. 

5.1.2. Host System Resident Monitor Interface 

An application program must interface with the host system resident monitor to 
create symbols (cipe_creat_symbol), access symbols (cipe_get_symbol), distri- 
bute data to the hypercube (cipe_cube_write_data), activate its counterpart 
hypercube module (cipe_cube_execute_module), and to perform a variety of 
other activities. Interfacing to the host resident monitor is done through func- 
tions CIPE provides for the tasks it expects a programmer to need to do. In 
this manner the job of the programmer is simplified and CIPE applications 
appear more uniform. A complete list of routines provided by CIPE may be 
found in Appendix C which is subdivided by routine functionality. 

The first time a host module is likely to need to interface with the host resident 
monitor is to retrieve input symbol(s) and to create output symbol(s). In Cli 
mode these functions happen transparently, as explained previously, so that Cli 
needs only to pass symbol table indices in its argument list. In menu mode it is 
necessary to retrieve the input symbol(s) and create the output symbol(s) from 
their. symbol names. A symbol is retrieved through the use of the command 
cipe get symbol, and created through the use of the command 

cipe_creat_symbol. In order to retrieve a symbol a variable must have been 
declared to store the symbol. The routine which retrieves symbols 

cipe_get_symbol must also be declared to return a pointer to a symbol struc- 
ture. In order to create a symbol, variables must have been declared to store 
the symbol and a symbol index. These declarations look like, 
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struct cipe_symbol *sin, *sout, *cipe_get_symbol(); 
int sindex; 

and may be found in the variable declaration section labeled symbol related. 
The commands are used by, 

sin = cipe_get_symbol(input); 

ok = cipe_creat_symbol(output,&sout,&sindex); 

and may be found in the CIPE host resident monitor interface section labeled 
symbol retrieval , which gives a completed menu interface. In the future, Cli 
and menu modes will function consistently for retrieving and creating symbols. 


Once an application program has completed its collection of information from 
the user, and has retrieved or created all necessary symbols, the program is 
ready to distribute data to the hypercube. If the programmer desires to use one 
of the standard distribution types, he/she may do so simply by using the rou- 
tine, cipe_cube_write_data, giving as its arguments only an input symbol and 
a distribution type keyword. Valid keywords for standard distributions are: 


BCAST_DIST 

HORIZ_DIST 

GRID.DIST 

VERT_DIST 


sends the entire data set to each node 
creates a horizontal distribution 
creates a grid distribution 
creates a vertical distribution 


The keywords may be used with the executive routine by the statement, 

ok = cipe_cube_write_data(input_symbol^listribution_type_keyword)', 

as may be found in, the host resident monitor interface section labeled 
standard_dist. 

The sample filter application allows the user to choose one of four data decom- 
positions, but to properly filter the image requires something other than a stan- 
dard distribution. This is provided by using the same command, 
cipe_cube_write_data, with a different keyword, CUSTOM_DIST, which 
allows the programmer to create any kind of a data decomposition desired. To 
use the CUSTOM_DIST keyword a programmer must first create a load map 
for the input symbol. In the case of standard distributions, 

cipe_cube_write_data completes the load map for the programmer. To create a 
load map a programmer must access the map’s storage location within the sym- 
bol. The attributes of a symbol can be cumbersome to reference. To assist the 
programmer in doing so, CIPE provides the following macro definitions. 
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CIPEDATAfsym&o/) 

CIPENAME(symto>/) 

CIPEFILE(sym&o/) 

CIPEmiMisymboO 

C IPE S B {symbol) 

CIPENBOsymto/) 

CIPESLIsym&o/) 

CIPENL {symbol) 

CIPESS {symbol) 

CIPENS (symbol) 

CIPE DATATYPE {symbol) 

CIPELOADTYPEfsymfo/) 

CIPELOADMAP(.yymfo>/) 

CIPEELEMENTSIZEfowZw/) 

CIPENUMELEMENTSCsymfo/) 

CIPEDATASIZECsymZw/) 


Pointer to the start of the data 
Name associated with the symbol 
File name associated with symbol 
Number of dimensions in the data 
Starting band of the data 
Number of bands of the data 
Starting line of the data 
Number of lines of the data 
Starting sample of the data 
Number of samples of the data 
Type of each data element 
Data distribution type 
Pointer to the load map of the data 
Size of an element of the data 
Number of elements in the data 
Total size of the data 


The structure definitions associated with these macros may be found in Appen- 
dix I under symbol.h. To create a load map a programmer needs to use the 
CIPELOADMAP(symbol) macro. CIPELOADMAP stores a pointer to an 
array containing the starting line, starting sample, starting band, number of 
lines, number of samples, and number of bands that each node is to receive 
when data is downloaded. The macros CIPESB, CIPENB, CIPESL, CIPENL, 
CIPESS, and CIPENS, store similar information for the entire data set as it 
exists in the host, which is not to be confused with the data pointed to by 
CIPELOADMAP which stores the information for the individual hypercube 
nodes. To make assignments to CIPELOADMAP a loop similar to the follow- 
ing must be created. 


for (i=0; \<number_of_cube_nodes ; i++) { 
CffELOADMAP(mpur_yym6o/)[i]*sl 
CIPELOADMAP(mpur_sym&>/)[i].nl 
CIPELOADMAP(mp«r_iymAoO[i]«ss 
CIPELOADMAP(wpuf_sym&>0[i].ns 
CIPELOADMAP(mpur_5ym£o/)[i].sb 
CIPELOADMAP(mpuf_5ym£o/)[i].nb 

} 


= starting line for node i; 

- number of lines for node i ; 

= starting sample for node i ; 

= number of samples for node /; 
= starting band for node i ; 

= number of bands for node i ; 


Once the load map has been created the data may be downloaded using the 
command: 


ok = cipe_cube_write_data(mpwf_.sym6<?/,CUSTOM_DIST); 

For the the sample application a horizontal decomposition with overlapping 
data regions is desired. The appropriate load map was created in the host 
resident monitor interface section labeled CUSTOM _DIST. 
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In addition to providing for the download of input data, a programmer must 
provide the means of uploading output data before invoking the host’s 
corresponding node module. To accomplish this the output symbol’s attributes 
must be assigned values. Typically, but not always, this involves assigning the 
output symbol’s attributes the same values as for the input symbol, since one 
would expect the output data to be of the same size, dimension, etc. and only 
differing in the actual contents of the data. This may be done by: 

CIPEDATATYPE (symbol_out) = CIPEDAT AT YPE(sym6o/_m); 

Similar statements should be made for other attributes. The load map of an out- 
put symbol may be specified for an application program in the same manner as 
for an input symbol. Again a programmer may choose a standard or customized 
distribution. While the input symbol’s loadmap implies the data area that each 
node must process, the output symbol’s loadmap implies the area of the output 
that each node is responsible to generate. A complete output symbol setup is 
shown in the host resident monitor interface section labeled output _symbo l . 

5.1.3. Hypercube Module Interface 

An application’s host module may request activation of its corresponding 
hypercube module with the following command. 

cipe_cube_execute_modu\e('' node_module_name"); 

This command interacts with the host resident monitor. The host resident mon- 
itor is only capable of dealing with one command at a time. For this reason, 
prior to the activation of the hypercube module, the input data must be distri- 
buted to the cube, the output symbol load map must have been established, and 
any other commands interacting with the host resident monitor must be com- 
plete. This command may be found in the sample program in the host resident 
monitor interface section labeled load hypercube-module. 

Once the hypercube module is activated, it waits for the parameters from the 
host module. In the future, CEPE will provide a function to pass parameters 
between the host and hypercube modules. At the current time, parameters must 
be passed using the hypercube’s Crystalline Operating System (CrOS) func- 
tions. In order to use CrOS functions, the file, cros.h, must be included. The 
parameter passing procedure for most applications may be accomplished with 
twd CrOS functions, bcastcp and mdumpcp. The bcastcp is for broadcasting a 
parameter value to all of the hypercube nodes and mdumpcp is for receiving an 
acknowledgment from each node. The CrOS function calls of the host module 
must be synchronized with the corresponding CrOS function calls (bcastelt and 
dumpelt) of the hypercube module in order for the parameters to be transferred 
properly. The hypercube side CrOS calls will be discussed in the hypercube 
module programming section. The CrOS commands bcastcp and mdumpcp 
are used as follows. 
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ok = bc2LStcp(pointer_to_data_to_be_sent,number_jof_bytes_to_send); 
if (ok == -1) { 

printf("cpfilter: error in bcastcp sending x to nodes\n"); 
return(-l); 

} 

ok = mdumpcp(pointer_to_rcv_data,max_bytes _per_node, 
pointer _to_array_by 'tes_rcvd); 
for (i=0; \<number_of processors; i++) 
if (packetsli] == NOK) 

printf("Error in node %d completing task jc\n",i); 

If a programmer desires to pass distinct parameters to each node, or to com- 
municate between the host and node modules for other functions, additional 
information on these and other hypercube commands may be found in the Mark 
III Hypercube Programmer’ s Manual. 

The parameter passing example can be found in the sample filter program in 
the hypercube module interface section labeled parameters. The parameter ack- 
nowledgment handshaking is not a mandatory requirement but is recommended 
for possible error detection prior to applying the data processing function. 

After the host program provides for the input parameters to be sent to the 
hypercube, it waits for the hypercube resident module to complete the data pro- 
cessing. If the programmer has chosen for the nodes to acknowledge reaching 
certain check points, the host module will need to provide for the receipt of the 
messages sent back. The rest of the work is left to the hypercube module. 

One host system resident module may activate more than one hypercube 
resident module sequentially, if desired. For example, a map projection pro- 
gram may activate a hypercube module for geometric transformation and then 
another module for resampling. A hypercube module is better designed to per- 
form a simple function so that it can be used by various host modules. CIPE 
intends to provide a large set of hypercube data processing modules for image 
processing applications so that an application programmer may need to write 
only host side modules calling the needed hypercube modules. 

5.2. HYPERCUBE RESIDENT PROGRAMMING 

The' hypercube resident application modules consist of the computationally 
intensive pan of the application programs. Similar to the host resident applica- 
tion modules, all hypercube resident modules have a common set of program 
procedures. Each hypercube module must interface with the host module to 
receive input parameters, must interact with the hypercube resident monitor for 
accessing input and output symbol structures, and must process data. All 
hypercube resident modules must include eltjnon.h and elt_symbol.h to provide 
some necessary variable and structure definitions. 
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Before processing any data, the hypercube module needs to read the necessary 
input parameters. The host module is using CrOS communication routines to 
send the parameters to the nodes and therefore the hypercube module needs to 
use the CrOS communication routines that correspond to those in the host. To 
utuilize CrOS communication routines the hypercube resident module must 
include cros.h. It has already been explained that it will be most common for 
the host to broadcast the same parameters to all the nodes. The command in 
the hypercube that corresponds to the host’s broadcast command is bcastelt. 
The programmer may like for the hypercube module to acknowledge its pro- 
gress to the host. The hypercube module may do this by periodically sending 
back information to the host. Each node may send distinct information back to 
the host by the use of the CrOS routine dumpelt. The commands bcastelt and 
dumpelt are used as follows. 

ok = bcastel t (po / nter_to_rcv_i nfo,max_bytes_to_rcv ) ; 

if (ok == -1) { 

printf("Error occurred in bcastelt receiving info *0); 
return(-l); 

} 

ok = dumpe\t(pointer_to_info_to_send,bytes_to_send); 

if (ok == -1) { 

printf("Error occurred in dumpelt sending info *0); 
return(-l); 

} 

If the bcastelt or dumpelt commands fail they will return a "-1". The first 
parameter in each of the routines must be a pointer and the second must be an 
integer. Examples of the use of these routines may be found in Figure 5.5 in 
the parameters section. All future references to an application program will 
refer to the sample hypercube resident module in Figure 5.5. 

The host module of an application program needs to pass input and output sym- 
bol names to the hypercube module. These will be passed as for all parameters 
as previously discussed. The entire input symbols and the output symbol attri- 
butes have already been passed and stored in the hypercube, but the hypercube 
module of the application needs to know the symbol names in order to retrieve 
them. Symbols are retrieved by using provided routines which interface with 
the hypercube resident monitor. Symbols may be retrieved using the routine, 
eIt_get_symbol. The routine elt_get_symbol takes the name of a symbol and 
a constant indicating whether it is a local or a global symbol, and it returns a 
pointer to the symbol’s position in the symbol table. Symbols created with the 
provided creat_symbol routine are global and are intended to be used to share 
data between application programs. Within the node module of the application 
program, the pointer to be used to reference global symbols must be declared 
globally as well. See the Global Symbols section of the sample node module. 
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Sifndef lint 

static char sccsid[]= 'Wo %G%“: 
sendif lint 

/* <*c\1% version ^cl^c. %G% • / 

^include <stdio.h> 

^include <ctype.h> 

^include <cros.h> 

^include <ermo.h> 

^include ,, elt_mon.h“ 

^include ■’el^symboLh” 

^define NOK 0 
^define OK l 

j* Global Variables • / 

int packet; 

int packet_size; 

extern doc ,nproc, proenum ; 

I* Global Symbols • / 

struct elt_symbol *sin* *sout, ♦elt_get_symbol(); 

nodefilter() HO de filter 

( 

elt_name input,ourput; 
int nJwjww.hnsw/weight; 
int i,jJcl.kZioff,ioffl,ok,window[2]; 
float •fweighusum; 

unsigned char *image_data,*creat_giobai(); 
register unsigned char *pl; 


I* 

packet_size = sizeof(packet); 


Parameters * / 


bcastelt(inpuusizeof(input)); l* input symbol * / 

sin = elt get_symbol(input*GLOBALSYM); 
if (sin = NULLS YM) packet = NOK; 
else packet = OK; 
ok=dumpclt(<fcpacket,packet_size); 
image^data = DATA(sin); 

bcastelt(outpuuslzeof(output)); /* output symbol * / 

sout = eit get symbol(output,GLOBALSYM); 
if (sout =* NULLS YM) packet - NOK; 
else packet = OK; 
ok=dumpelt(Apacket,packet_size); 

/* window size * / 


/* weights * / 


End_Parameters * / 

I* Filter Process * / 

/* make the sum of the weight matrix to be 1 - normalize the weight matrix • / 
fweighc = (float *)malloc(nlw*njw*sizeof(float)); 

sum =0.0; 

for (kl=0; kl<nlw*nsw; kl-M-) sum (float) weightfkl]; 

for (kl=0; kl<nlw*nsw; kl++) fweightfkl] = (float )weight(kl] /sum; 


be as te!t(wmdow,jixeof( window)); 
nlw = wmdow(O); 
nsw = windowfl]; 

printf(* window size (%d %d)Vn H jilw,niw); 
hnsw = nsw (2; 

weight = (int *)maUoc(idw*niw*staof(!iit)); 
ok = bcastelt(weight,niw*nsw*slaof(Iiit)); 
printf("weight received (%d)>tr,ok); 


l 


Figure 5.5 Spatial Filter Node Program 
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...nodefilter 

for (kl=0; kl<nlw; kl-M-) 

for (k2=0; k2<nsw; k2++) 

prmtf(' , weight(%d,%d) = %fW\kl,k2Jweight[kl*nsw+k2]); 
f* apply filter * / 

pnntf("filter starts (%d %d ),(%x %x),(%d %d)\n”, 

NL(sin)J s iS(sin),DATA(sin),DATA(sout) f NL(sout)*NS(sout)); 
ioff = 0; 

for (i=0; i<NL(sin>-nlw; i++) { 

pi = DATA(sout)4-i*NS(sout)+hnsw; 
for (j=0; j<NS(sin>-nsw; j++) { 
sum = 0.0; 
ioff 1 = ioff+j; 

for (kl=0; kl<nlw; kl*»-+) ( 

for (k2=0; k2<nsw; k2-M-) 

sum += (float)image_datt(ioffl +k2] • fweight[kl*nsw+k2]; 
ioffl += NS(sin); 

) 

If (sum < 0.0) sum = 0.0; /* under saturation * / 

if (sum > 255.0) sum* 255.0; /* over saturation • / 

*pl++ = sum; 

) 

ioff += NS(sin); 

) 

primf("filter is completed^*); 

frec( weight); 
frcc(fwcight); 
packet = OK; 

ok * dumpelt(&packeuslzeof(iiit)); 

/. 


End Filter • / 
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Once all the parameters have been read and the symbols retrieved the applica- 
tion program may process the data. The data processing part of the application 
program may be written similarly to the way it would be for a sequential pro- 
gram. The algorithm is likely to be the same with only the bounds on the data 
set changing. The hypercube resident module may provide status reports to the 
host resident module as desired by use of the CrOS dumpelt routine. 

Upon completion of the node module the hypercube resident monitor will be 
ready to receive another command. The application program needs to take no 
action to return the processed data to the host. The data will remain resident in 
the hypercube for processing by another application until the user chooses to 
retrieve the symbol to the host for display or storage, or to delete the symbol. 

5.3. INTEGRATING APPLICATION PROGRAMS INTO CIPE 

Each of the application program’s two modules, the host resident module and 
the hypercube resident module, must be appropriately linked with CIPE in 
order to run. This happens through the use of Makefiles like the samples pro- 
vided. Figure 5.6 provides a Makefile for a host resident application module. 

CC=ccc 

CIPEDIR=/spacely/ufs/cipe 
CIPE = $(CIPEDIR)/cipe 
CFLAGS= -g -I$(CIPEDIR)/include 
APPLS= host_resident_appl_module_name 
LINK= $(CIPEDIR)/appl/cp/CPLINK 

host_resident_appl_module_name: host_resident_appl_module_name.o \ 
$(CIPE) 

$(LINK) $(CIPE) $@ 

Figure 5.6 Host Resident Application Module Makefile 

A programmer needs only to place his/her own host resident application module 
name where it says host_resident_appl_module_name. This links host modules 
with CIPE and the host resident monitor. Figure 5.7 provides a makefile for a 
hypercube resident application module. 
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CC=/jane/ufs/cube/bin/cc68 

CIPE DIR=/spacely/ufs/ci pe 

CIPE = $(CIPEDIR)/cipe 

CFLAGS= -g -I$(CIPEDIR)/include 

APPLS= cube_resident_appl_modu!e_name 

ELT_MONITOR= $(CIPEDER)/cube/eIt_monitor/elt_mon 

LINK= $(CIPEDIR)/appl/elt/ELTLINK 

cube_resident_appl_module_name: cube_resident_appl_module_name.o \ 
$(ELT_MONITOR) 

$(LINK) $(ELT_MONITOR) $@ 

Figure 5.7 Hypercube Resident Application Module Makefile 

A programmer needs only to place his/her own hypercube resident application 
module where it says cube_resident_appl_module_name. This links cube 
resident modules with the hypercube resident monitor. 

Application programs linked as described may be called within CIPE from 
menu or Cli mode. They may be called from menu mode by going to the appl 
menu option which allows the user to type in the application function name and 
the requested application program will be loaded. In order for a user to call 
his/her own application function from Cli mode, an entry for the application 
must be added to the function dictionary. All applications for use by CIPE are 
listed in a. function dictionary. Each entry of the function dictionary has one of 
the following forms, depending on whether or not the application returns a 
value: 

FUNCTION name ( argument-list ) 

RETURNS ( argument-list ) 

HELP "help message ” 

PATHNAME location-list 

PROCEDURE name ( argument-list ) 

PATHNAME location-list 

where an argument-list , possibly empty, is structured as 
[access-type] [ value-type ] prompt-message 


for 
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access-type INPUT or OUTPUT 

value-type INTEGER, FLOAT, DOUBLE, STRING, or BOOLEAN 

prompt-message " string " 

and a location-list is structured as 
pathname USES system 


Two examples follow. 

function filter(input "In", 
input "Box width", 
input "Box height", 
input "Wgts", 
input "Loadtype") 

returns "Out" pathname "/ufs/cipe/appl/cp/cpfiiter" 

procedure cleardisplay( ) 

pathname "/ufs/cipe/appl/cp/cleardisplay" 


5.4. APPLICATIONS WITHOUT A COPROCESSOR 

Application programming in CIPE without the use of a coprocessor is much 
simpler as there is only a host resident module, and therefore no data distribu- 
tion or parameter passing to the coprocessor is necessary. Figure 5.8 is a filter 
program which runs in CIPE without the use of a coprocessor. Figure 5.2, dis- 
cussed previously, was an example of a host resident module of a filter pro- 
gram which used the JPL/Caltech Mark III as a coprocessor. Close comparison 
of Figure 5.2 and Figure 5.8 will demonstrate the similarities and differences 
between application programming in CIPE with and without a coprocessor. 
These similarities and differences will be presented here. 

The variable declaration section of Figures 5.2 and 5.8 are similar. The sec- 
tions labeled menu related and symbol related are identical in the two exam- 
ples. Figure 5.8 lacks any hypercube-related variables because it is not 
intended to use the hypercube or any other coprocessor. Additional variables 
are found in the area labeled application related in order to support the data 
processing that will now occur in the host instead of in a coprocessor. 

The user interface section of the two examples is similar, as well. Without the 
hypercube, the filter program does not need to request a data load type of the 
programmer. Therefore, the user interface section labeled menu lacks the def 
statement which reads the load type, and the count of def statements assigned 
to param_count is one less. The lack of a load type means that the user 
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#ifndef lint 

static char sccsidn= ,,qr oW% %G%"; 
#endif lint 


}* %M% version %!%, %G% • / 
include <stdio.h> 

^Include <ctype.h> 

^include <ermo.h> 

#include <cros.h> 

^include '’cipeappl.h" 

seqfilterO 

( 


/ 

/****************** VARIABLE declaration SECTION ****************** / 

/ 

I* Menu Relaxed * / 

struct par am *params; 
int param_count; 
int check_filter(); 


seqfilter 


l* Symbol Related * f 

cl P c _ s y m _ namc inpuuoutput; 

struct cipe_ symbol *sin, *sout, *cipe_get_symbol(); 
int s index; 


I* Application Related * / 

Int niw, nsw, hnsw, window [2], * weight, *weightptr, 
int kUc2,i,j t ioff,ioffl; 

int ok; 

float sum,*fweight; 
unsigned char *image_data; 
unsigned char register *pl; 


/ 

USER INTERFACE SECTION *•♦******•**•***•****• / 

I* 

If (MENU MODE) ( 

param_count = 3; 

params = (struct param * )malloc (slzeoffstruct param) * param_count); 

def(params.O,"input symbol name M ,STRING f iiiput,WIDJ2,LINE,2, 

REQ.END); 

def(paramj,l," output symbol name ”,STRING,output,WID,32,LINE,3, 

REQ.END); 

def(par«n*/Z, M filter window(nlw,nsw) '\INT, window JNCR.4.WID, 10, 

LINE, 4 JXJP, 2, REQ.END); 

If (getpar(perami, par am_count,check_fil ter, NOHELP)) return; 
free(parame); 


Menu * / 


params * (struct param • )malloc<siieofl(stnict param)*window[0]*window[l]); 
weight * (Int *)malkx(window[0]*window(l]*sl2eof(lnt)); 


for (i=*0; i<window[l); i«M*) ( 

def(params,i,”weight values "JNT.weight-H, 
INCR^lzeof(lnt)*wmdow[0],LINE,2, 

ENTRYUNE,3,ENTRYCOUi*10,DUP,window[0],GROUPAREQ,END); 

} 

if (getpar(params,window[l] l NOECH]CNOHELP)) return; 


Figure 5.8 Spatial Filter Program Without a Coprocessor 
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...seqfilter 

J* EndJMenu * i 

j* Cli • / 

else ( 

sin = ARGPTR(O); 
window(0] = *(lnt *)ARGDATA(l); 
wmdow[l] = *(lnt *)ARGDATA(2); 
weight * (int *)mailoc(window[0j*window[lj*sizeof(lnt)); 
weightpcr = (Int *)ARGDATA(3); 
for (i=0; i< window [0 ] * windo w[ 1 ] ; i-M-) 
weight[i] = weightptrfi]; 
sout = RESULTP: 

} 


(* EndjCli * / 

* / 

/ ******** CIPE HOST RESIDENT MONITOR INTERFACE **•***•• / 

/ 

/* * Symbol Retrieved • / 

If (MENU_MODE) ( 

sin = cipe_get_symbol(input); 

ok = cipe_creat_symbol(output,&sout,&sindex); 

) 


cipe_host_write_data(sin); 

/* — End_Symbol Retrieval • / 

/* Output Symbol * / 

CIPEDATATYPE(souc) = CIPEDATATYPE(sin); 

CIPENS(sout) = CIPENS(sin); 

CIPENL(sout) * CIPENL(jin); 

CIPENB(sout) = CIPENB(sm); 

CIPENDIM(sout) * CIPENDIM(sin); 

CIPEDATA(sout) = (unsigned char *)malloc(CIPEDATASIZE(sout)); 


!* End ^Output ^Symbol * I 

/ 

DATa PROCESSING ••*••••*•***•*•*******♦* / 

/* Filter Process * / 

nlw = window [0]; 
nsw = window[l]; 
hnsw = nsw 12; 


/* moke the sum of the weight matrix to be l - normalise the weight matrix * / 
f weight = (float *)maHoc(rdw*nsw*sizeof(float)); 

sum =0.0; 

for (k 1 =0 kl<nlw*nsw; kl++) sum +« (fk>at)weight[kl]; 

for (kl=0; kl<nlw*nsw; kl++) fweighrfkl) = (float) weightfkl] /sum; 

for (kl=0, kl<niw; kl-n+0 

for (k2=0; k2<nsw; k2++) 

pnntf(”weight(%d,%d) * %f^i”Jcl,k2 t fweight(kl*nsw44t2]); 

I* apply filter • / 

Image data = CIPEDATA(sin); 

ioff =T 0; 

for (i=0; i<CPENL(sin)-nlw; i-t-+) { 

pi = CIPEDATA(sout)+i*CIPENS(sout)+hnsw; 
for (j=0; ;<CIPENS(sin)-nsw; j++) { 
sum = 0.0, 
ioff 1 = ioff+j; 

for (kl=0; kl<nlw; kl++) { 

for fk2=0; k2<nsw; k2<M-) 
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sum -k= (float)image_data(ioffl+k2] 
ioffl += CIPENS(sin); 

) 

If (sum < 0.0) sum = 0.0; 

If (sum > 255.0) sum= 255.0; 

♦pl-M- = sum ; 

) 

ioff CIPENS(sm); 
pnntf( M ioff= %d, pi = 0x%xV\ioff,pl); 

} 

princf(TiIter is completed^"); 

free( weight); 
free(fweight); 

/* — — EndJFilter * 

} 

check_ filter(params ^number ,v alue) 
struct par am *params; 
int number; 

union (lnt i; double f; char *s;} value; 

{ 

int error, whereis; 
error = 0; 
switch(number){ 

case 0: whereis=cipe_get_symbol_index(value.s); 

If (whereis — NO SYMBOL) error * 1; 

If (error) priiuf( "symbol does not exist"); 
break; 

case 1: whereis=cipe_get_symboi_index(value.s); 

If (whereis != NO SYMBOL) error * 2; 
if (error) printf( "symbol already exists"); 
break; 

case 2: if (((valued) % 2) = 0) error * 3; 

if (error) printf("must be odd number"); 

break; 

) 


• fweight[kl*nsw+k2J; 

/* under saturation • / 
/* over saturation • / 


...seqfilter 


/ 

check _ filter 


If (error != 0) return(-l); 
else return(O); 
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interface section labeled Cli has one less argument in its argument list, and it 
therefore lacks the line that previously read the load type from the argument 
list. 

The cipe host resident monitor interface section no longer provides for distri- 
buting data to the hypercube. Instead, the function cipe_host_write_data is 
called to make sure that the data of the input symbol is resident in the host sys- 
tem memory. Prior to the function call the data of the input symbol may be in 
the file, in the coprocessor, or already in the host system memory, depending 
on previous functions applied to the symbol. An example of the function call 
may be found in the area labeled retrieve jsymbol. The cipe host resident mon- 
itor interface section also still provides for assigning the attributes of the output 
data symbol which is found in the area labeled output_symbol. Previously, 
when the filter program used the hypercube, no data space was allocated for the 
output symbol in the host because the data resided in the hypercube. When 
outside of the application program the user chose to read the data back from 
the hypercube the space would have been created. Now it is necessary to allo- 
cate space in the host for the output symbol because that is where the data will 
reside. The last line of the section labeled output symbol provides for this. 

CIPEDATA(sout) = malloc(CIPEDATASIZE(sout)); 

The remaining portion of Figure 5.8 provides for the actual filtering of the data. 
Previously, in Figure 5.2, a node module would have been activated and the 
host module would have passed its parameters and waited for execution. Now 
the same filtering algorithm used in the nodes resides in the host and executes 
on the entire image instead of the subset each node previously operated on. 
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6. FUTURE DIRECTION 

The previous five sections described the features and implementation details of 
CIPE with respect to the user environment, programming environment, and 
internal management of data and image processing functions. The user 
environment emphasizes friendly access to provided functions, and the pro- 
gramming environment provides system architecture-independent subroutine 
layers for user interface, file I/O, hypercube utilization, and display device 
manipulation. A symbol-oriented data management and an incremental program 
loading mechanism are implemented for more efficient utilization of the con- 
current system, and to overcome the system I/O bottleneck common in a high 
rate data processing environment. The future direction of CIPE will be divided 
in three parts, based on the three distinctive characteristics of CIPE: as an 
interactive image processing executive, as a concurrent system executive, and 
as a high rate data processing executive. 

The future CIPE as an interactive image processing executive will address a 
new environment where a user and programmer may become one. The funda- 
mental desire of every user is to express his/her thought process and to experi- 
ment with ideas without having to go through the cumbersome transformation 
process of programming. Such an environment is generally referred to as an 
automatic programming environment. Computer scientists have approached 
automatic programming via development of high level languages which reduce 
the effort of transforming a human logical process into a computer’s machine 
instructions. Although high level languages significantly simplify programming 
procedures, it is far from achieving true automatic programming. Automatic 
programming in a generic sense may be an illusion, since one generic language 
cannot possibly understand nor provide all users’ needs. However, within a 
well-defined user community, such an environment may be achievable. The 
scoping of the user community and characteristics of users are essential for a 
successful implementation of a proper user environment. 

The future goal of CIPE is to provide such an automatic programming environ- 
ment for an image processing user community with scientifically oriented users. 
The goal will be pursued in three major directions: a user interface, an applica- 
tion tool box, and higher level image processing language development. The 
future user interface will be directed toward developing various expressional 
tools which can compensate the limitations of typing from a terminal. The tools 
will utilize more advanced window-based terminals, display devices, and vari- 
ous input sources. The development of an application tool box will be pursued 
via analyzing image processing algorithms to extract a set of basic image pro- 
cessing operators (primitives). The complete set of operators will allow any 
image processing to be performed using a proper combination of the operators. 
Finally, an image processing language which allows manipulation of the image 
processing operators will be studied and developed. The language will allow 
usage in an interpretive mode as well as in a programming mode. 
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The future CIPE as a concurrent system executive will incorporate various con- 
current architectures and provide a more advanced programming environment 
for such architectures. An automatic parallel compiler will be researched to 
remove the requirement of parallel programming for a specific architecture. The 
compiler will not be general purpose, but will be oriented toward an image pro- 
cessing programming environment where a large data set is distributed among 
multiple nodes in a concurrent system for execution of a same function. 

The future CIPE as a high rate data processing executive will provide necessary 
testbed functions for EOS era. Such functions will include sensor simulation, 
benchmarking of systematic processing procedures, and/or simulation of various 
architectural concepts for on-board data processing and analysis. 
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Directory Filename Link Module 

include cipe.h 

symbol.h 

funclib.h 

image_hdr.h 

menus.h 

opcodes.h 

builtin.h 

cp_mon.h 

elt_mon.h 

elt_data.h 

elt_symbol.h 


main 

cipe.c 

dictionlex.l 

libmain.a 


y.tab.h 

dictioay 

lex.yy.c 

parser2.sed 

symbol. c 

funclib.c 


cli 

codegen.c 

ops.c 

y.tab.c 

lex.yy.c 

parser.c 

libcli.a 

menu 

cipemenu.c 

dispmenu.c 

setmenu.c 

applmenu.c 

libmenu.a 

exec 

docli.c 

doclisubs.c 

doset.c 

dodisp.c 

doplotc 

doplot3d.c 

doplotsubs.c 

libdo.a 


doio.c 

dofile.c 

dobltin.c 

dobltinc.c 

docall.c 

doload.c 

docube.c 

dosymbol.c 


PRECEDING PAGE BLANK NOT FILMED 
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Directory 

cp_monitor 

elt_monitor 


appl/cp 


appl/elt 


/usr/locaiyiib 


Filename Link Module 

cp_mon.c cp_mon.o 

cp_data.c cp_data.o 


elt_mon.c elt_mon 

elt_symbol.c 

elt_module.c 

elt_data.c 

elt_bltin.c 


cpfilter.c 

cpmed 

cpgeom.c 

cpzoom.c 

cphist.c 

cpproj.c 

cprender.c 

cpfft2.c 

nodefilter.c 

nodemed 

nodegeom.c 

nodezoom.c 

nodehist.c 

nodeproj.c 

noderender.c 

nodefft2.c 


SUPPORTING LIBRARIES 


ydlib.a 

xdlib.a 

ivasx.a 

ivas.a 

xanth.a 


yamm.a 


CL 
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Subroutine: struct code_seg_def *cipe_init_code_seg(name,workspace) 

File: codegen.c 

Input: char *name; 

unsigned char workspace; 

Output: None 

Function: Cipe_init_code_seg creates a new code segment, complete with symbol table and func- 

tion dictionary. This code segment then becomes the current code segment; the previous 
code segment is saved. The function returns a pointer to the new code segment. 

Suggested Modification: 

None 

S ubroutine : ci pe_restore_code_seg() 

File: codegen.c 

Input: None 

Output: None 

Function: Returns to the previous (parent) code segment. The current code segment is left intact. 

The function returns -1 on error, and 0 otherwise. 

Suggested Modification: 

None 

Subroutine: cipe_arith_op(op,argl,arg2,result) 

File: codegen.c 

Input: unsigned int op; 

symbolnum argl,arg2, result; 

Output: None 

Function: Cipe_arith_op generates an arithmetic instruction to be executed by the Command Line 

Interpreter either immediately (as in the case of a request to print out the sum of two 
numbers), or in the future execution of a user-defined workspace or function. A tem- 
porary variable is created in the code segment symbol table, if necessary, and the in- 
struction is saved. The function returns the symbol number (symbol table index) of the 
result variable or NO_SYMBOL on error. 

Suggested Modification: 

None 


precede page blank not f|lmeo 
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Subroutine: 

cipe_assign(left_side,right_side) 

File: 

codegen.c 

Input: 

symbolnum left_side,right_side; 

Output: 

None 

Function: 

Cipe_assign handles assignments requested interactively or in the execution of a user- 
defined workspace or function. Assignments are optimized away by the function, if pos- 
sible. The function returns -1 on error, and 0 otherwise. 

Suggested Modification: 
None 

Subroutine: 

cipe_index(var,index_list) 

File: 

codegen.c 

Input: 

symbolnum var; 

struct indexlist_def *indexjist; 

Output: 

None 

Function: 

Cipe Jndex generates a subscript instruction to be executed by the Command Line Inter- 
preter either immediately (as in the case of a request to display a small region of an im- 
age), or in the future execution of a user-defined workspace or function. The function 
returns the symbol number (symbol table index) of the result variable or NOJSYMBOL 
on error. 

Suggested Modification: 
None 

Subroutine: 

cipe_cal!(func,expr_!ist) 

File: 

codegen.c 

Input: 

functionnum func; 

struct exprlist_def *expr Jist; 

Output: 

None 

Function: 

Cipe_call generates a request to call the specified function to be executed by the Com- 
mand Line Interpreter either immediately (as in the case of an interactive function call), 
or in the future execution of a user-defined workspace or function. The function returns 
the symbol number (symbol table index) of the result variable or NO_SYMBOL on er- 
ror. 

Suggested Modification: 
None 
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Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_br(labeIJoc) 

codegen.c 

struct instruction ♦labeljoc; 

None 

Cipejbr takes an instruction pointer (label location) and generates an instruction to 
branch to that location. This is normally called in the compilation of a conditional or 
looping construct. The function returns -1 on error, and 0 otherwise. 


Suggested Modification: 
None 


Subroutine: 

File: 

Input: 

Output: 

Function: 


struct instruction *cipe_add_br_placeholder() 

codegen.c 

None 

None 

Cipe_add_br_placeholder generates a placeholder instruction in the compilation of a 
looping or conditional construct in a user-defined workspace or function. The place- 
holder instruction is initially an NOP, which is normally replaced later in code genera- 
tioa The function returns a pointer to the placeholder instruction. 


Suggested Modification: 
None 


Subroutine: 

File: 

Input: 

Output: 

Function: 


ci pe_patch_br(br Joe, labeljoc) 

codegen.c 

struct instruction *labelJoc; 
struct instruction *brJoc; 

Cipe_patch_br patches a previously compiled unconditional branch instruction using 
new information. The absolute location in labeljoc is converted to a code-segment- 
relative location and stored in the specified instruction, together with a branching opcode 
in case the previous opcode was a placeholder. This function is normally used in the 
compilation of conditional and looping constructs. The function returns -1 on error, and 
0 otherwise. 


Suggested Modification: 
None 
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Subroutine: 

cipe_patch_brz(br_Ioc,label_loc,exprl) 

File: 

codegen.c 

Input: 

struct instruction *labelJoc; 
symbolnum exprl; 

Output: 

struct instruction *br_loc; 

Function: 

1 

Cipe_patchJ>rz patches a previously compiled branch-on-zero instruction using new in- 
formation. The absolute location in label Joe is converted to a code-segment-relative lo- 
cation and stored in the specified instruction, together with a branch-on-zero opcode in 
case the previous opcode was a placeholder. The expression to use in the condition is 
also replaced. This function is normally used in the compilation of conditional and 
looping constructs. The function returns -1 on error, and 0 otherwise. 

Suggested Modification: 
None 

Subroutine: 

cipe_patch_brfor(br Joe, label Joc,exprl,expr2^tep) 

File: 

codegen.c 

Input: 

struct instruction *brJoc,*labelJoc; 
symbolnum exprl,expr2,step; 

Output: 

None 

Function: 

Cipe_patch_brfor patches a previously compiled branch-in-for instruction using new in- 
formation. The absolute location in label Joe is converted to a code-segment-relative lo- 
cation and stored in the specified instruction, together with a branch-in-for opcode in 
case the previous opcode was a placeholder. The expressions denoting the limits of the 
loop and the step size to use are also replaced. The function returns -1 on error, and 0 
otherwise. 

Suggested Modification: 
None 

Subroutine: 

cipe_set_attr(attr, value) 

File: 

codegen.c 

Input: 

unsigned int attr; 
symbolnum value; 

Output: 

None 

Function: 

Cipe_set_attr generates an instruction to set a particular system attribute. This instruc- 
tion may either be executed immediately (as in the case of an interactive processor allo- 
cation), or in the future execution of a user-defined workspace or function. The function 
returns -1 on error, and 0 otherwise. 

Suggested Modification: 
None 
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Subroutine: 

File: 

Input: 

Output: 

Function: 


ci pe_wscmd(cmd_code,ws) 

codegen.c 

unsigned int cmd_code; 
symbolnum ws; 

None 

Cipe_wscmd generates an instruction to reference (load, save, edit) a workspace on 
disk. This may either be executed immediately (as in the case of an interactive 
workspace load), or in the future execution of a different user-defined workspace or 
function. The function returns -1 on error, and 0 otherwise. 


Suggested Modification: 
None 


Subroutine: 

File: 

Input: 

Output: 

Function: 


ci pe_shellcmd(cmd) 

codegen.c 

char *cmd; 

None 

Cipe_shellcmd generates an instruction to execute an arbitrary Unix shell command, 
such as to edit a file or to list the files in a directory. Such instructions may either be 
executed immediately (as in the case of an interactive date request) or in the future exe- 
cution of a user-defined workspace or function. The function returns —1 on error, and 0 
otherwise. 


Suggested Modification: 
None 


Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_quit() 

codegen.c 

None 

None 

Cipe_quit generates an instruction to quit the current workspace, function, or terminal 
session. The instruction is executed either immediately (as in the case of an interactive 
QUIT command or CTRL D), or in the future as part of a user-defined workspace or 
function. The function returns -1 on error, and 0 otherwise. 


Suggested Modification: 
None 
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Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_symboIs() 

codegen.c 

None 

None 

Cipe_symbols generates an instruction to list the currently defined symbols. This in- 
struction may be executed either immediately (as in the case of an interactive SYM- 
BOLS command), or in the future as part of a user-defined workspace or function. The 
function returns -1 on error, and 0 otherwise. 


Suggested Modification: 
None 


Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_functions() 

codegen.c 

None 

None 

Cipe_functions generates an instruction to list the currently defined functions. This in- 
struction may be executed either interactively (as in the case of a FUNCTIONS com- 
mand) or in the future execution of a user-defined workspace of function. Note that ex- 
ecution of this instruction shows both builtin and user-defined functions, but only those 
functions available in the current context The function returns -1 on error, and 0 other- 
wise. 


Suggested Modification: 
None 


Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_tracesO 

codegen.c 

None 

None 

Cipe_traces generates an instruction to show the currently set traces. This is executed 
either immediately (as in the case of a keyboard TRACES command), or in the future 
execution of a user-defined workspace or function. The function returns -1 on error, 
and 0 otherwise. 


Suggested Modification: 
None 
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Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_show(index) 
codegen.c 
symbolnum index; 

None 

Cipe_show generates an instruction to list the specified user-defined function. This is 
executed either immediately (as in the case of a keyboard SHOW command), or in the 
future execution of a user-defined workspace or function. The function returns -1 on 
error, and 0 otherwise. 


Suggested Modification: 
None 


Subroutine: 

File: 

Input: 


Output: 

Function: 


cipe_define(name,codeseg,args,resuIt, text, scope) 

codegen.c 

char *name,*text; 
struct code_seg_def *codeseg; 
struct arglist_def *args; 
unsigned int result, scope; 

None 

Cipe_define generates an instruction associating a name in the current context with a 
specified user-defined function. This is executed either immediately (as in the case of a 
keyboard DEFINE command), or in the future execution of a user-defined workspace or 
function which defines subordinate pieces of code. Note that functions defined using 
this instruction are defined only in the context of execution. The function returns -l on 
error, and 0 otherwise. 


Suggested Modification: 
None 


Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_print(exprs) 

codegen.c 

struct expr!ist_def *exprs; 

None 

Cipe_print generates an instruction to display the value of a particular variable. This 
instruction is either executed immediately (as in the case of an interactive PRINT com- 
mand), or in the future execution of a user-defined workspace of function. The function 
returns -1 on error, and 0 otherwise. 


Suggested Modification: 
None 
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Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_read_symbol(symbol, filename) 

codegen.c 

symbolnum symbol; 
symbolnum filename; 

None 

Cipe_read_symbol generates an instruction to read a symbol value from a specified file. 
This instruction may either be executed immediately (as in the case of a keyboard 
READ command) or in the future execution of a user-defined workspace or function. 
The function returns -1 on error, and 0 otherwise. 


Suggested Modification: 
None 


Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_write_symbol(symbol, filename) 

codegen.c 

symbolnum symbol, filename; 

None 

Cipe_write_symbol generates an instruction to write a symbol value to a specified file. 
This instruction may either be executed immediately (as in the case of a keyboard 
WRITE command) or in the future execution of a user-defined workspace or function. 
The function returns -1 on error, and 0 otherwise. 


Suggested Modification: 
None 


Subroutine: 

File: 

Input: 

Output: 

Function: 


ci pe_display(image, location) 

codegen.c 

symbolnum image; 
struct location_def location; 

None 

Cipe_display generates an instruction to display a symbol at a specified location on a 
display device. This instruction may either be executed immediately (as in the case of a 
keyboard DISPLAY command) or in the future execution of a user-defined workspace 
or function. The function returns -1 on error, and 0 otherwise. 


Suggested Modification: 
None 
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Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_menu(on) 
codegen.c 
int on; 

None 

Cipe_menu generates an instruction to switch to or from using menus as the main user 
interface. This instruction may either be executed immediately (as in the case of a key- 
board MENU command) or in the future execution of a user-defined workspace or func- 
tion, but if executed in a workspace or function, will not take effect until execution 
completes. The function returns -1 on error, and 0 otherwise. 


Suggested Modification: 
None 


Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_help() 

codegen.c 

None 

None 

Cipe_help generates an instruction to provide help. This is normally executed immedi- 
ately as part of a keyboard HELP command, but might be useful in user-defined 
workspaces as well. The function returns -1 on error, and 0 otherwise. 


Suggested Modification: 
None 


Subroutine: 

File: 

Input: 

Output: 

Function: 


ci pe_sa ve_scalar(scalar,type) 

codegen.c 

unsigned int scalar; 
int type; 

None 

Cipe_save_scalar takes a scalar value and a value type, and stores the value in the 
current symbol table. A temporary variable (type c) is created and storage allocated. 
The function returns the symbol number (symbol table index) of the new variable, or 
NO_SYMBOL on error. 


Suggested Modification: 
None 
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Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_conneet_constants(constl,const2) 

codegen.c 

symbolnum constl,const2; 

None 

Cipe_connect_constants takes two constants as specified by their symbol numbers 
(symbol table indices in the current context), and makes one multiple element constant 
of the two. Either of the original constants may have several values, but they are as- 
sumed to be of at most one dimension, i.e., scalars or vectors. The result is a vector 
whose size is the sum of the sizes of the original constants, and referenced by the sym- 
bol table location of the first component constant. The second constant is deleted. Data 
types are changed (e.g., from int to float) if necessary for compatibility. The function 
returns -1 on error, and 0 otherwise. 


Suggested Modification: 
None 


Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_save_string(string) 

codegen.c 

char *string; 

None 

Cipe_save_string takes a string value and stores the value in the current symbol table. 
A temporary variable (type c) is created and storage allocated. The number of dimen- 
sions is set to 0, the number of bands and lines to 1, and the number of samples to the 
length of the string plus the terminating null byte. The data type is set to 
STRING_TYPE. The function returns the symbol number (symbol table index) of the 
new variable, or NO_SYMBOL on error. 


Suggested Modification: 
None 


Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_save_keyword(keyword_nutn) 

codegen.c 

unsigned int keyword_num; 

None 

Cipe_save_keyword takes a keyword number and stores it as a value in the current 
symbol table. A temporary variable (type c) is created and storage allocated. Keywords 
are stored much as scalars, but are of type KEYWORD_TYPE. The function returns 
the symbol number (symbol table index) of the new variable, or NO_SYMBOL on er- 
ror. 


Suggested Modification: 
None 
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Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_save_booIean(boolean_num) 

codegen.c 

unsigned int booIean_num; 

None 

Cipe_save_boolean takes a boolean value and stores it in the current symbol table. A 
temporary variable (type c ) is created and storage allocated. Booleans are stored much 
as scalars, but are of type BOOL_TYPE. The function returns the symbol number 
(symbol table index) of the new variable, or NO_SYMBOL on error. 


Suggested Modification: 
None 


Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_disassemble(address, buffer) 

codegen.c 

struct instruction ’address; 
char ’buffer; 

Cipe_disassemble writes a textual description of a compiled instruction to the specified 
buffer. The description includes the address of the instruction, the instruction mnemon- 
ic, and symbolic names of the instruction arguments and results. The function returns 
-1 on error, and 0 otherwise. 


Suggested Modification: 
None 


Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_get_temp(type) 

codegen.c 

char type; 

None 

Cipe_get_temp creates a temporary symbol of the specified type and returns the symbol 
table index, or NO_SYMBOL on error. Temporary symbols come in a variety of types, 
depending on the application, and have names of the form _xn, where x is the type (e.g., 
c for constants encountered in compiling command lines or user-defined workspaces and 
functions) and n is a number. Numbers uniquely identify symbols, but symbols are 
referenced internally by the symbol table index. 


Suggested Modification: 
None 
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Subroutine: cipe_istemp(symbol) 

File: codegen.c 

Input: symbolnum symbol; 

Output: None 

Function: Cipejstemp returns true (non-zero) if the specified symbol number (symbol table in- 

dex) references a temporary symbol. This is equivalent to checking whether the first 
character of the symbol name is an underscore (_), since underscore is not a valid char- 
acter for starting user-defined variable names. 

Suggested Modification: 

None 

Subroutine: cipe_save_instruction(iptr) 

File: codegen.c 

Input: struct instruction *iptr; 

Output: None 

Function: Cipe_save_instruction takes a pointer to an instruction (as created by any of the in- 

struction generation routines documented here) and stores it at the next location in the 
current code segment The function first checks for sufficient storage, allocating more if 
necessary, then stores the instruction in the next available location, increments the 
number of instructions, and if requested by a previous TURN ON CODEGEN TRACE 
command, prints out a disassembled version of the instruction. The function returns -1 
on error, and 0 otherwise. 

Suggested Modification: 

None 

Subroutine: cipe_clear_code() 

File: codegen.c 

Input: None 

Output: None 

Function: Cipe_clear_code removes the code in the current code segment, resetting the next in- 

struction pointer and the code length to their initial values. 

Suggested Modification: 

Allocated data structures used by the removed code should be properly freed. 
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Subroutine: yylex() 

File: lexsrc 

Input: None 

Output: None 

Function: A lexical analyzer, yylex, is generated by the Unix utility lex using the CIPE Cli file 

lexsrc. This function reads from the CIPE input buffers, tracing lexical analysis if re- 
quested using the TURN ON LEX TRACE command, separates the input into tokens, and 
then returns these tokens to the parser (yyparse ) as needed. The function is called au- 
tomatically by the parser, so no explicit calls by the programmer are necessary. 

Suggested Modification: 

None 


Subroutine: cipeJexJnitO 

File: lexsrc 

Input: None 

Output: None 

Function: Cipejexjnit performs initializations before lexical analysis. These include setting up 

and initializing buffer space. The function returns —1 on error, and 0 otherwise. 

Suggested Modification: 

None 

Subroutine: cipe_lex_push_stream(input_file, verbose) 

File: lexsrc 

char *input_file; 
unsigned char verbose; 

None 

Cipejex_push_stream opens the specified input file and gets future command line in- 
put from there. A new stream description structure is created and the structure for the 
previous stream is pushed onto a stack. The verbose argument indicates whether or not 
input from the new stream should be echoed on the terminal. This is most useful when 
a command has been edited and the modified command needs to be redisplayed during 
execution. The function returns -1 on error, and 0 otherwise. 

Suggested Modification: 

None 


Input: 

Output: 

Function: 
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Subroutine: cipejex_prep_buffer() 

File: lexsrc 

Input: None 

Output: None 

Function: Cipe_lex_prep_buffer prepares Cipe lexical analysis buffers to receive more input. It 

checks to make sure that a stream is still available to read from, and saves the last com- 
mand in case the user wants to edit it It then resets pointers and lexical analysis status 
variables and returns. The function returns -1 on error, and 0 otherwise. 

Suggested Modification: 

None 

Subroutine: cipe_lex_get_cmdline() 

File: lexsrc 

Input: None 

Output: None 

Function: Cipejex_get_cmdline gets a command line from the current input stream and stores it 

in an internal lexical analysis buffer. If the current input stream is the standard input 
(i.e., input is being taken from the keyboard rather than from a workspace file or a tem- 
porary editor file), it prints the prompt; either the start-of-command prompt or the in- 
dented line-continuation prompt. If the user requests editing (using CTRL E), it calls 
for editing and the reading of the edited command as a new input stream. Otherwise, 
the keyboard input is simply stored. If input is coming from a file, the file is read and 
the input line saved; at end-of-file, the stream descriptor is popped off of the stack. Re- 
gardless of where input comes from, the function manages buffer space, increasing it if 
necessary, removes leading spaces and comments, and if in verbose mode, echos the in- 
put line to the user. The function returns the first character of the new input line. 

Suggested Modification: 

None 
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Subroutine: cipejex_lookup_reserved_word(token,at_bol) 

File: lexsrc 

Input: char *token; 

int at_boI; 

Output: None 

Function: Cipe_lex_lookup_reserved_word takes a token and a flag indicating whether or not the 

token is the first on its line, and returns true (non-zero) if the token is a reserved word. 
The input token is first converted to lower case and if syntactically eligible, is checked 
against the list of known system attributes. System attributes containing an underscore 
may also be specified using a space and with component words abbreviated, requiring 
some local parsing to recognize correct specifications. If the token is not an attribute, it 
is checked against lists of other reserved words (e.g., quit) and booleans and keywords 
(e.g., on, ivas). The function returns -1 if not a reserved word, and the type of reserved 
word otherwise. The beginning-of-line flag is currently ignored. 

Suggested Modification: 

None 

Subroutine: cipe_lex_edit_input() 

File: lexsrc 

None 
None 

Cipejex_edit_input creates a temporary file and writes into it the current or last com- 
mand. It then enables the user to edit the file using a standard system editor and causes 
the file to be set up as a new input stream. When execution of the file has finished, the 
file is deleted and this function returns. Note that in this case lexical analysis is actually 
recursive. If the command edited had invoked workspaces, several levels of lexical 
analysis would have been present at the same time. The function returns -1 on error, 
and 0 otherwise. 

Suggested Modification: 

None 

Subroutine: yyerror(s,bufpos) 

File: lexsrc 

Input: char *s,*bufpos; 

Output: None 

Function: Yyerror is called automatically by the parser when an error message needs to be print- 

ed. If the current input stream is the standard input (i.e., input is coming from the key- 
board), the offending line is displayed with a carat Q underneath marking the error. If 
input is coming from a file, the filename and line number are displayed. The function 
returns -1 on error, and 0 otherwise. 

Suggested Modification: 

None 


Input: 

Output: 

Function: 
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Subroutine: cipe_lex_cleanup() 

File: lexsrc 

Input: None 

Output: None 

Function: Cipejex_cleanup removes from the stack all pending workspace- and file-based input 

streams. Input is taken from the keyboard, subsequently. The function returns -1 on 
error, and 0 otherwise. 

Suggested Modification: 

None 

Subroutine: cipe_ensure_buffer_space(nbytes) 

File: lexsrc 

int nbytes; 

None 

Cipe_ensure_buffer_space makes sure that the lexical analysis buffers are large enough 
to hold the specified number of additional characters. If the buffers are too small, more 
space is allocated. The initial buffer size is 1024 characters. More space may be need- 
ed in the case of long function definitions, which as single commands must fit into the 
buffers at once. 

Suggested Modification: 

None 

Subroutine: cipejt_builtin(lhs_data,rhs_data,result_data,datasize,datatype) 

File: ops.c 

Input: char *lhs_data,*rhs_data; 

unsigned int datasize, datatype; 

Output: char *result_data; 

Function: Cipejt_builtin takes pointers to two scalars or vectors of the specified type and returns 

a boolean scalar or vector indicating, for each pair of values, their relationship. This is 
normally used by the executive when the size of the data items is not sufficient to justify 
downloading to a coprocessor. Input arguments are assumed to be of the same type. 
The function returns -1 on error, and 0 otherwise. 

Suggested Modification: 

The function should accept types other than integer and float 


Input: 

Output: 

Function: 
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Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_lte_builtin(lhs_data,rhs_data,result_data, datasize, datatype) 

ops.c 

char *lhs_data,*rhs_data; 
unsigned datasize, datatype; 

char *result_data; 

Cipejte_builtin takes pointers to two scalars or vectors of the specified type and re- 
turns a boolean scalar or vector indicating, for each pair of values, their relationship. 
This is normally used by the executive when the size of the data items is not sufficient 
to justify downloading to a coprocessor. Input arguments are assumed to be of the same 
type. The function returns -1 on error, and 0 otherwise. 


Suggested Modification: 

The function should accept types other than integer and float 


Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_eq_builtin(lhs_data,rhs_data,result_data, datasize, datatype) 

ops.c 

char *Ihs_data,*rhs_data; 
unsigned datasize, datatype; 

char *result_data; 

Cipe_eq_builtin takes pointers to two scalars or vectors of the specified type and re- 
turns a boolean scalar or vector indicating, for each pair of values, their relationship. 
This is normally used by the executive when the size of the data items is not sufficient 
to justify downloading to a coprocessor. Input arguments are assumed to be of the same 
type. The function returns -1 on error, and 0 otherwise. 


Suggested Modification: 

The function should accept types other than integer and float 


Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_ne_builtin(lhs_data,rhs_data,result_data, datasize, datatype) 

ops.c 

char *Ihs_data,*rhs_data; 
unsigned datasize, datatype; 

char *result_data; 

Cipe_ne_builtin takes pointers to two scalars or vectors of the specified type and re- 
turns a boolean scalar or vector indicating, for each pair of values, their relationship. 
This is normally used by the executive when the size of the data items is not sufficient 
to justify downloading to a coprocessor. Input arguments are assumed to be of the same 
type. The function returns -1 on error, and 0 otherwise. 


Suggested Modification: 

' The function should accept types other than integer and float 
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Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_gte_builtin(lhs_data,rhs_data,result_data, datasize, datatype) 

ops.c 

char *lhs_data,*rhs_data; 
unsigned datasize, datatype; 

char *result_data; 

Cipe_gte_builtin takes pointers to two scalars or vectors of the specified type and re- 
turns a boolean scalar or vector indicating, for each pair of values, their relationship. 
This is normally used by the executive when the size of the data items is not sufficient 
to justify downloading to a coprocessor. Input arguments are assumed to be of the same 
type. The function returns -1 on error, and 0 otherwise. 


Suggested Modification: 

The function should accept types other than integer and float 


Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_gt_builtin(lhs_data,rhs_data,result_data,datasize,datatype) 

ops.c 

char *lhs_data,*rhs_data; 
unsigned datasize, datatype; 
char *result_data; 

Cipe_gt_builtin takes pointers to two scalars or vectors of the specified type and returns 
a boolean scalar or vector indicating, for each pair of values, their relationship. This is 
normally used by the executive when the size of the data items is not sufficient to justify 
downloading to a coprocessor. Input arguments are assumed to be of the same type. 
The function returns -1 on error, and 0 otherwise. 


Suggested Modification: 

The function should accept types other than integer and float 


Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_and_builtin(lhs_data,rhs_data,result_data, datasize, datatype) 

ops.c 

char *lhs_data,*rhs_data; 
unsigned datasize, datatype; 

char *result_data; 

Cipe_and_builtin takes pointers to two scalars or vectors of the specified type and re- 
turns a boolean scalar or vector indicating, for each pair of values, whether or not they 
are both non-zero. This is normally used by the executive when the size of the data 
items is not sufficient to justify downloading to a coprocessor. Input arguments are as- 
sumed to be of the same type. The function returns -1 on error, and 0 otherwise. 


Suggested Modification: 

■ The function should accept types other than 4-byte integer. 
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Subroutine: 

File: 

Input: 

Output: 

Function: 


cipeorbuiltin(lhs_data,rhs_data,result_data,datasize,datatype) 

ops.c 

char *lhs_data,*rhs_data; 
unsigned datasize, datatype; 

char *result_data; 

Cipe_or_builtin takes pointers to two scalars or vectors of the specified type and re- 
turns a boolean scalar or vector indicating, for each pair of values, whether or not either 
of the values is non-zero. This is normally used by the executive when the size of the 
data items is not sufficient to justify downloading to a coprocessor. Input arguments are 
assumed to be of the same type. The function returns -1 on error, and 0 otherwise. 


Suggested Modification: 

The function should accept types other than 4-byte integer. 


Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_bitand_builtin(lhs_data,rhs_data,result_data,datasize,datatype) 

ops.c 

char *lhs_data,*rhs_data; 
unsigned datasize,datatype; 

char *result_data; 

Cipe_bitand_builtin takes pointers to two scalars or vectors of the specified type and 
returns a boolean scalar or vector indicating, for each pair of values, the value of their 
bit-wise AND. This is normally used by the executive when the size of the data items 
is not sufficient to justify downloading to a coprocessor. Input arguments are assumed 
to be of the same type. The function returns -1 on error, and 0 otherwise. 


Suggested Modification: 

The function should accept types other than 4-byte integer. 


Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_bitor_builtin(lhs_data,rhs_data,result_data,datasize,datatype) 

ops.c 

char *lhs_data,*rhs_data; 
unsigned datasize,datatype; 

char *result_data; 

Cipe_bitor_builtin takes pointers to two scalars or vectors of the specified type and re- 
turns a boolean scalar or vector indicating, for each pair of values, the value of their 
bit-wise OR. This is normally used by the executive when the size of the data items is 
not sufficient to justify downloading to a coprocessor. Input arguments are assumed to 
be of the same type. The function returns -1 on error, and 0 otherwise. 


Suggested Modification: 

The function should accept types other than 4-byte integer. 
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Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_bitxor_builtin(lhs_data,rhs_data,result_data, datasize, datatype) 

ops.c 

char *lhs_data,*rhs_data; 
unsigned datasize, datatype; 

char *result_data; 

Cipe_bitxor_builtin takes pointers to two scalars or vectors of the specified type and 
returns a boolean scalar or vector indicating, for each pair of values, the value of their 
bit-wise XOR. This is normally used by the executive when the size of the data items 
is not sufficient to justify downloading to a coprocessor. Input arguments are assumed 
to be of the same type. The function returns -1 on error, and 0 otherwise. 


Suggested Modification: 

The function should accept types other than 4-byte integer. 


Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_plus_builtin(Ihs_data,rhs_data,result_data,datasize,datatype) 

ops.c 

char *lhs_data,*rhs_data; 
unsigned datasize, datatype; 

char *result_data; 

Cipe_p!us_builtin takes pointers to two scalars or vectors of the specified type and re- 
turns a boolean scalar or vector indicating, for each pair of values, their sum. This is 
normally used by the executive when the size of the data items is not sufficient to justify 
downloading to a coprocessor. Input arguments are assumed to be of the same type. 
The function returns -1 on error, and 0 otherwise. 


Suggested Modification: 

The function should accept types other than integer and float 


Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_minus_builtin(lhs_data,rhs_data,result_data,datasize,datatype) 

ops.c 

char *lhs_data,*rhs_data; 
unsigned datasize, datatype; 

char *result_data; 

Cipe_minus_builtin takes pointers to two scalars or vectors of the specified type and 
returns a boolean scalar or vector indicating, for each pair of values, their difference. 
This is normally used by the executive when the size of the data items is not sufficient 
to justify downloading to a coprocessor. Input arguments are assumed to be of the same 
type. The function returns -1 on error, and 0 otherwise. 


Suggested Modification: 

The function should accept types other than integer and float 
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Subroutine: 

File: 

Input: 

Output: 

Function: 


cipe_mult_builtin(lhs_data,rhs_data,result_data, datasize, datatype) 

ops.c 

char ♦lhs_data,*rhs_data; 
unsigned datasize, datatype; 

char *result_data; 

Cipe_mult_builtin takes pointers to two scalars or vectors of the specified type and re- 
turns a boolean scalar or vector indicating, for each pair of values, their product. This is 
normally used by the executive when the size of the data items is not sufficient to justify 
downloading to a coprocessor. Input arguments are assumed to be of the same type. 
The function returns -1 on error, and 0 otherwise. 


Suggested Modification: 

The function should accept types other than integer and float 


Subroutine: 

cipe_div_bui!tin(lhs_data,rhs_data,result_data, datasize, datatype) 

File: 

ops.c 

Input: 

char *lhs_data,*rhs_data; 
unsigned datasize, datatype; 

Output: 

char *result_data; 

Function: 

Cipe_div_builtin takes pointers to two scalars or vectors of the specified type and re- 
turns a boolean scalar or vector indicating, for each pair of values, their quotient. This 
is normally used by the executive when the size of the data items is not sufficient to jus- 
tify downloading to a coprocessor. Input arguments are assumed to be of the same type. 
The function returns -l on error, and 0 otherwise. 

Suggested Modification: 

The function should accept types other than integer and float 

Subroutine: 

yyparseO 

File: 

parse r.y 

Input: 

None 

Output: 

None 

Function: 

Yyparse is a parser generated by the Unix yacc utility using the Cipe Cli source file 
parser. y. It performs all command line parsing (calling yylex for tokens as necessary) 
and the corresponding error detection, calling instruction generation routines to create 
pseudo code in the current code segment. These instructions are then executed either 
immediately or in the future invocation of a user-defined workspace or function. The 
function provides for several type of tracing, as specified by the user. 


Suggested Modification: 
, None 
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C.l Symbol Manager 

Subroutine: ci pe_creat_symbol(sname,sptr,sindex) 

File: symbol.c 

Input: char *sname (symbol name); 

Output: struct cipe_symbol *sptr; 

int sindex (symbol array inpdex); 

Function: Creates a symbol entry in the symbol table under the symbol name sname and allocates 

a memory space for a symbol structure. Initializes each field of the symbol structure 
with default values and returns the pointer to the symbol structure (sptr) and the index 
(sindex) of the symbol table entry. 

Suggested Modification: 

Simplify calling sequence to sindex = cipe_creat_symbol(sname). 

Subroutine: struct cipe_symbol *cipe_get_symbol(sname) 

File: symbol.c 

Input: char *sname; 

Output: struct cipe_symbol *sptr; 

Function: Returns a symbol structure pointer of a given symbol name. 

Suggested Modification: 

Simplify calling sequence to sindex = cipe_creat_symbol(sname). 

Subroutine: cipe_delete_symbol(sindex) 

File: symbol.c 

Input: int sindex; 

Output: None 

Function: Deletes a symbol entry from the symbol table, deallocates the symbol structure, and 

reorganizes the symbol table. 

Suggested Modification: 

None 

Subroutine: struct cipe_symbol *cipe_symbol_index_to_ptr(sindex) 

File: symbol.c 

Input: int sindex; 

Output: None 

Function: Returns a symbol structure pointer to a symbol in the symbol table indexed by sindex. 

Suggested Modification: 

None 
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Subroutine: char *cipe_symbol_index_to_name(sindex) 

File: symbol. c 

Input: int sindex; 

Output: None 

Function: Returns a symbol name of a symbol in the symbol table entry indexed by sindex. 

Suggested Modification: 

None 

Subroutine: cipe_dump_symboI_table( verbose) 

File: symbol.c 

Input: int verbose; 

Output: None 

Function: Lists out symbol information. 

Suggested Modification: 

None 

Subroutine: cipe_func_delete_symbol(sname) 

Input: char *sname; 

Output: None 

Function: Deletes the symbol entry from the symbol table in the host and the nodes. 

Suggested Modification: 

Change sname into sindex. 

Subroutine : ci pe_clear_temp_symbols() 

File: symbol.c 

Input: None 

Output: None 

Function: Deletes temporary symbols from the symbol table. 

Suggested Modification: 

None 


i 
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C.2 Program Manager 

Subroutine: cipe_func_application(function_name) 

File: doload.c 

Input: char *function_name; 

Output: None 

Function: Loads an application function and executes the function. 

Suggested Modification: 

None 

Subroutine: cipe_load_moduIe(function_file) 

File: doload.c 

Input: char *function_fi!e; 

Output: None 

Function: Loads the executable application program file function_file into the predefined program 

area. 

Suggested Modification: 

None 

Subroutine: cipe_execute_module() 

File: doload.c 

Input: None 

Output: None 

Function: Jumps to the program area and starts execution. 

Suggested Modification: 

None 
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C.3 File I/O 

Subroutine: cipe_func_read_from_file(sname, header) 

File: dofile.c 

Input: char *sname; 

strcut imagejidr *header; 

Output: None 

Function: Reads the file whose name is specified in the filename field of the symbol sname. Any 

subset of the file can be specified in the area description fields of the symbol 
(sl,ss,sb,nl,ns,nb). The data is read into the malloced symbol data area. 

Suggested Modification: 

Instead of using a symbol name, a symbol table entry index should be used. 

Subroutine: cipe_func_write_to_fiIe(filename, sname) 

File: dofile.c 

Input: char *filename; 

char *sname; 

Output: None 

Function: Writes the data of the symbol sname to the file filename. 

Suggested Modification: 

Instead of using a symbol name, a symbol table entry index should be used. 

Subroutine: struct imagejidr *cipe_getjmagejieader(filename) 

File: dofile.c 

Input: char *filename; 

Output: None 

Function Opens a header file (filename.hdr), parses the header information, and returns a pointer 

to the image_header structure. 

Suggested Modification: 

None 

Subroutine: cipe_putjmagejieader(filename,header) 

File: dofile.c 

Input: char *fi!ename; 

struct imagejidr header; 

Output: None 

Function: Creates a header file (filename.hdr) and writes the header buffer into the header file. 

Suggested Modification: 

None 
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Subroutine: cipe_open(filename, option) 

File: do file. c 

Input: char ‘filename; 

int option; 

Output: 

Function: Same as Unix open. 

Suggested Modification: 

None 

Subroutine: cipe_creat(filename,header) 

File: dofile.c 

Input: char ‘filename; 

struct image_hdr ‘header; 

Output: None 

Function: Executes cipe_put_image_header(filename,header) and the Unix command 

cr eat( filename, 0644) to create a file header and file. 

Suggested Modification: 

None 

Subroutine: cipe_read(filename, buffer, nbytes) 

File: dofile.c 

Input: char ‘filename; 

int nbytes; 

Output: unsigned char ‘buffer 

Function: Same as Unix read. 

Suggested Modification: 

None 

Subroutine: cipe_write(filename,buffer,nbytes) 

File: dofile.c 

Input: char ‘filename; 

int nbytes; 

Output: unsigned char ‘buffer 

Function: Same as Unix write. 

Suggested Modification: 

None 
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C.4 Display 

Subroutine: cipe_func_draw(plane, sname, loc) 

File: dodisp.c 

Input: int plane; 

char *sname; 
int loc[2]; 

Output: None 

Function: Draws the data of the symbol sname on the image plane plane starting at the location 

described by loc [0] (line) and loc[l] (sample). When the data type is not character type, 
the data type is converted prior to display. 

Suggested Modification: 

Instead of symbol name, symbol table entry index may be used. 

Subroutine: cipe_func_mssdraw(sname,band,loc) 

File: dodisp.c 

Input: int plane; 

char *sname; 

Output: None 

Function: Draws a selected band (band) of the multispectral data (three dimensional) of the sym- 

bol sname starting at the location described by loc[0] (line) and loc[l] (sample). When 
the data type is not character type, the data type is converted prior to display. 

Suggested Modification: 

Instead of symbol name symbol table entry index may be used 

Subroutine: cipe_func_mssplot(sname > xrange,yrange) 

File: doplotc 

Input: char *sname; 

float xrange[2]; 
int yrange[2]; 

Output: None 

Function: This routine is an interactive plotting routine where a user can continue plotting a 

specified subarea of the specified dataset (sname). Each spectrum will be plotted with 
different color using x axis as wavelength range and y axis as intensity value range. 

Suggested Modification: 

None 
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Subroutine: 

File: 

Input: 


Output: 

Function: 


cipe_func_plot3d(input, viewelev, viewazi, plotoff sets) 

doplot3d.c 

char *input; 
float viewelev; 
float viewazi; 
float plotoffsets[2]; 

None 

This routine plots image data using the intensity as z axis. For specified elevation and 
azimuth of a viewer (viewelev, viewazi), the projected input data are plotted with the 
piotoffsets as an origin of coordinates(0,0,0). 


Suggested Modification: 
None 
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C.5 Hypercube Interface 

Subroutine: cipe_cube_buiItin(function_name,lhs,rhs, result) 

File: docube.c 

Input: int function_name; 

char *lhs; 
char *rhs; 

Output: char *result 

Function: Performs an operation^, I, specified by the function_name on two sym- 

bols (lhs - left-hand side symbol name, rhs- right-hand side symbol name) and stores the 
result in the output symbol result. 

Suggested Modification: 

None 

Subroutine: cipe_cube_execute_module(module_name) 

File: docube.c 

Input: char *module_name; 

Output: None 

Function: Loads hypercube resident application program module into the hypercube and executes 

the program. 

Suggested Modification: 

None 

Subroutine: cipe_cube_compose_loadmap(sptr) 

File: docube.c 

Input: 

Output: None 

Function: Composes a loadmap for a symbol pointed by the sptr according to the specified load- 

type and its data characteristics. 

Suggested Modification: 

None 

Subroutine: cipe_cube_read_loadmap(sptr) 

File: docube.c 

Input: struct cipe_symbol *sptr; 

Output: None 

Function: Reads a loadmap of a symbol pointed by sptr from the cube. 

Suggested Modification: 

None 
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Subroutine: cipe_cube_writeJoadmap(sptr) 

; File: docube.c 

Input: struct cipe_symboI *sptr; 

Output: None 

Function: Writes a loadmap of a symbol pointed by sptr to the cube. 

Suggested Modification: 

None 

Subroutine: cipe_cube_read_data(sptr) 

File: docube.c 

Input: struct cipe_symboI *sptr; 

Output: None 

Function: Reads data of a symbol pointed by sptr from the cube. 

Suggested Modification: 

None 

Subroutine: ci pe_cube_write_data(sptr4oadtype) 

File: docube.c 

Input: struct dpe_symbol *sptr; 

int loadtype; 

Function: Writes data of a symbol pointed by sptr to the cube according to the loadtype. 

Suggested Modification: 

None 
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Subroutine: elt Jnit( ) 

File: elt_mon.c 

Input: none 

Output: none 

Function: Initializes some global hypercube parameters, sets up the symbol table, and initializes 

the type size array. 

Suggested Modification: 

None 

Subroutine: elt_panic( ) 

File: elt_mon.c 

Input: char *str 

Output: none 

Function: Terminates node monitor, prints a corresponding message, and turns on the light emit- 

ting diodes Oeds) on the hypercube. 

Suggested Modification: 

None 

Subroutine: getstring(str) 

File: elt_module.c 

Input: none 

Output: char *str 

Function: Hypercube gets a string from the control processor and stores it in str. 

Suggested Modification: 

None 

Subroutine: getint(iptr) 

File: elt_module.c 

Input: none 

Output: int *iptr 

Function: Hypercube gets an integer from the control processor and stores it in iptr. 

Suggested Modification: 

None 
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Subroutine: elt_load_moduIe( ) 

File: elt_module.c 

Input: none 

Output: int td_size 

int bss_size 

Function: Hypercube receives a module for execution. 

Suggested Modification: 

None 

Subroutine: elt_execute_module( ) 

File: elt_module.c 

Input: none 

Output: none 

Function: Begins execution of the current module. 

Suggested Modification: 

None 

Subroutine: elt_init_symtab( ) 

File: elt_symbol.c 

Input: none 

Output: none 

Function: Initializes the symbol table. 

Suggested Modification: 

None 

Subroutine: SYMBOL *elt_get_symbol(name, global) 

File: elt_symbol.c 

Input: char *name 

int global 

Output: none 

Function: Goes and gets the symbol with name name. 

Suggested Modification: 

None 


HYPERCUBE RESIDENT EXECUTIVE SUBROUTINES 


D— 5 


SYMBOL *elt_create_symbol(name, global, size, datatype) 
elt_symbol.c 

char *name 
int global 
int size 
int datatype 

Output: none 

Function: Creates a symbol with name name and returns a pointer to it. 

Suggested Modification: 

None 

Subroutine: SYMBOL *elt_de!ete_symbol(sym) 

File: elt_symbol.c 

Input: SYMBOL *sym 

Output: none 

Function: Deletes a symbol from the symbol table. 

Suggested Modification: 

None 

Subroutine: eIt_lock_globaI(sym) 

File: elt_symbol.c 

Input: SYMBOL *sym 

Output: none 

Function: Locks a global symbol to prevent its data from being moved during memory compac- 

tioa 

Suggested Modification: 

None 

Subroutine: elt_unlock_global(sym) 

File: elt_symbol.c 

Input: SYMBOL *sym 

Output: none 

Function: Unlocks a global symbol to allow its data to be moved during memory compaction. 

Suggested Modification: 

None 


Subroutine: 

File: 

Input: 
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Subroutine: elt_buiUin( ) 

File: elt_bltin.c 

Input: none 

Output: none 

Function: Runs in the hypercube to set up for and call the builtin function the user requested. 

Suggested Modification: 

None 

Subroutine: eltjt_bui!tin(lhs_data,rhs_data,result_data,datasize, datatype) 

File: elt_bltin.c 

Input: unsigned char *Ihs_data, *rhs_data 

int datasize, datatype 

Output: unsigned char *result_data 

Function: Less than function. 

Suggested Modification: 

None 

Subroutine: elt_lte_builtin(lhs_data,rhs_data,result_data, datasize, datatype) 

File: elt_bltin.c 

Input: unsigned char *lhs_data, *rhs_data 

int datasize, datatype 

Output: unsigned char *result_data 

Function: Less than or equal to functioa 

Suggested Modification: 

None 

Subroutine: elt_eq_builtin(lhs_data,rhs_data,result_data, datasize, datatype) 

File: elt_bltin.c 

Input: unsigned char *lhs_data, *rhs_data 

int datasize, datatype 

Output: unsigned char *result_data 

Function: Equal function. 

Suggested Modification: 

None 
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Subroutine: elt_ne_builtin(lhs_data,rhs_data,result_data,datasize, datatype) 

File: elt_bltin.c 

Input: unsigned char *lhs_data, *rhs_data 

int datasize, datatype 

Output: unsigned char *result_data 

Function: Not equal function. 

Suggested Modification: 

None 

Subroutine: elt_gte_builtin(lhs_data,rhs_data,result_data,datasize, datatype) 

File: elt_bltin.c 

Input: unsigned char *lhs_data, *rhs_data 

int datasize, datatype 

Output: unsigned char *result_data 

Function: Greater than or equal to functioa 

Suggested Modification: 

None 

Subroutine: elt_gt_builtin(lhs_data,rhs_data,result_data, datasize, datatype) 

File: elt_bltin.c 

Input: unsigned char *lhs_data, *rhs_data 

int datasize, datatype 

Output: unsigned char *result_data 

Function: Greater than function. 

Suggested Modification: 

None 

Subroutine: elt_and_buHtin(lhs_data,rhs_data,result_data, datasize, datatype) 

File: elt_bltin.c 

Input: unsigned char *lhs_data, *rhs_data 

int datasize, datatype 

Output: unsigned char *result_data 

Function: AND function. 

Suggested Modification: 

None 
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Subroutine: elt_or_buiItin(lhs_data,rhs_data,result_data, datasize, datatype) 

File: elt_bltin.c 

Input: unsigned char *Ihs_data, *rhs_data 

int datasize, datatype 

Output: unsigned char *result_data 

Function: OR function. 

Suggested Modification: 

None 

Subroutine: elt_bitand_builtin(lhs_data,rhs_data,resuit_data, datasize, datatype) 

File: elt_bltin.c 

Input: unsigned char *lhs_data, *rhs_data 

int datasize, datatype 

Output: unsigned char ♦result_data 

Function: Bitwise AND function. 

Suggested Modification: 

None 

Subroutine: eIt_bitor_buiItin(lhs_data,rhs_data,result_data, datasize, datatype) 

File: elt_bltin.c 

Input: unsigned char *lhs_data, *rhs_data 

int datasize, datatype 

Output: unsigned char *result_data 

Function: Bitwise OR function. 

Suggested Modification: 

None 

Subroutine: elt_bitxor_builtin(lhs_data,rhs_data,result_data, datasize, datatype) 

File: elt_bltin.c 

Input: unsigned char *lhs_data, *rhs_data 

int datasize, datatype 

Output: unsigned char *result_data 

Function: Bitwise XOR function. 

Suggested Modification: 

None 
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Subroutine: elt_plus_builtin(lhs_data,rhs_data,result_data, datasize, datatype) 

File: elt_bltin.c 

Input: unsigned char *!hs_data, *rhs_data 

int datasize, datatype 

Output: unsigned char *result_data 

Function: Addition function. 

Suggested Modification: 

None 

Subroutine: elt_minus_builtin(lhs_data,rhs_data,result_data, datasize, datatype) 

File: elt_bltin.c 

Input: unsigned char *lhs_data, *rhs_data 

int datasize, datatype 

Output: unsigned char *result_data 

Function: Subtraction function. 

Suggested Modification: 

None 

Subroutine: elt_mult_builtin(lhs_data,rhs_data,result_data, datasize, datatype) 

File: elt_bUin.c 

Input: unsigned char *lhs_data, *rhs_data 

int datasize, datatype 

Output: unsigned char *result_data 

Function: Multiplication function. 

Suggested Modification: 

None 

Subroutine: elt_div_builtin(lhs_data,rhs_data,result_data, datasize, datatype) 

File: elt_bltin.c 

Input: unsigned char *!hs_data, *rhs_data 

int datasize, datatype 

Output: unsigned char *result_data 

Function: Division function. 

Suggested Modification: 

None 
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Subroutine: elt_read_data(symbol) 

File: elt_data.c 

Input: struct elt_symbol ’symbol 

Need the desired data decomposition and the load map which are stored in the structure. 

Output: struct e!t_symbol ’symbol 

Function: This subroutine runs in the nodes of the hypercube to read data from the control proces- 

sor and place it in the nodes according to the decomposition type and the load map 
stored in the symbol. It communicates with the corresponding control processor routine, 
cube_write( ). 

Suggested Modification: 

None 

Subroutine: elt_write_data(symbol) 

File: elt_data.c 

Input: struct elt_symbol ’symbol 

Reads the old load map from the control processor. 

Output: Image data is sent back to the control processor. 

Function: This routine, which runs in the hypercube, sends data from the nodes to the control pro- 

cessor. The decomposition type of the current data is taken from the old load map. The 
desired manner of sending back the data is taken from the decomposition type and the 
load map stored in symbol. This subroutine communicates with the corresponding con- 
trol processor subroutine, cube_read( ). 

Suggested Modification: 

Further test returning the data using a CUSTOM decomposition. 

Subroutine: eIt_redist_data(symbol) 

File: elt_data.c 

Input: struct elt_symbol ’symbol 

Reads old load map from control processor. 

Output: struct elt_symbol ’symbol 

Function: This routine runs in the hypercube to move data between decompositions within the 

cube. Only certain transitions have been implemented and some may never be possible. 
Load type for current data is taken from the old load map, and data is redistributed ac- 
cording to the load type and load map stored in symbol. This subroutine communicates 
with the corresponding control processor subroutine, cube_redist( ). 

Suggested Modification: 
none 
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Subroutine: 

mv_horiz_grid_vert(symbol, oldloadmap, exchchan) 

File: 

elt_data.c 

Input: 

struct eltjoadmap ‘oldloadmap 
int exchchan 

Output: 

struct elt_symbol ‘symbol 
struct eltjoadmap ‘oldloadmap 

Function: 

This subroutine runs in the hypercube to move data from a horizontal decomposition to 
a grid decomposition, or from a grid decomposition to a vertical decomposition. It reads 
the current data decomposition type and load map from oldloadmap, exchanges ap- 
propriate data along the channel specified in exchchan, and alters oldloadmap to reflect 
the data that is now stored in symbol. 

Suggested Modification: 


none 

Subroutine: 

mv_vert_grid_horiz(symbol, oldloadmap, exchchan) 

File: 

elt_data.c 

Input: 

struct eltjoadmap ‘oldloadmap 
int exchchan 

Output: 

struct elt_symboI ‘symbol 
struct eltjoadmap *oldloadmap 

Function: 

Moves data from a vertical decomposition to a grid decomposition, or from a grid 
decomposition to a horizontal decomposition. Reads current data decomposition type 
and load map from oldloadmap, exchanges appropriate data along the channel specified 
in exchchan, and alters oldloadmap to reflect the data now stored in symbol. 

Suggested Modification: 


none 

Subroutine: 

cube_read(symbol, oldloadmap) 

File: 

cp_data.c 

Input: 

struct cipe_symbol ‘symbol 
struct loadmap ‘oldloadmap 

Output: 

Image data is returned from the nodes of the hypercube to the control processor. 

Function: 

Runs in the control processor to read image data from the hypercube back to the control 
processor. The hypercube uses oldloadmap to know how the data is stored in symbol, 
and uses the load map and decomposition type information stored in symbol to know 
how the user desires to read the data back. 

Suggested Modification: 


none 
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Subroutine: 

File: 

Input: 

Output: 

Function: 


cube_write( symbol, oldloadmap) 

cp_data.c 

struct cipe_symbol "symbol 
struct loadmap "'oldloadmap 

struct cipe_symbol "symbol 

Data is read from the control processor and stored in the nodes of the hypercube accord- 
ing to the load type and load map stored in symbol. Oldloadmap contains information 
for the entire image. 


Suggested Modification: 
none 


Subroutine: 

File: 

Input: 

Output: 

Function: 


cube_redist(symbol, oldloadmap) 

cp_data.c 

struct cipe_symbol "symbol 
struct loadmap "oldloadmap 

struct cipe_symboI "symbol 

Within the cube data is moved from one decomposition to another. The control proces- 
sor sends oldloadmap to the cube to inform it how the data is currently stored. The 
desired data decomposition and load map are stored in symbol. 


Suggested Modification: 
none 
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Built-in Functions 


Arithmetic Operations 

: +, *. / 

Logical Operations 

: ==, !=, >, <, &&, II 

Bit manipulations 

: &, 1 , 


Display Functions 

Allocation 

Stretch 

Draw 

MssDraw (multispectral data) 

Zoom 

Histogram 

Cursor 

Erase 


Plot Functions 

Mssplot 

3dplot 


Image Enhancement 

Spatial convolution filter 
Histogram stretch 

Frequency domain windowing (under development) 


B&W, Color, Pseudo 
Linear, Table 
B&W, Color 


Read, Write 
Image, Graphics 


Geometric correction 

Tie point 
Map projection 
Size 


Data Classification 

Spectral classification 

Textural classification (under development) 
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1. INTRODUCTION 

One of the most time-consuming yet necessary tasks of writing any piece of interactive software 
is the development of a user-interface. Frequently, the development of even a very simple interface 
takes up valuable time that might be much better devoted to the design and implementation of the 
underlying task. Yamm (Yet another menu-manager) is an application-independent menuing package, 
designed to remove much of the difficulty and save much of the time inherent in the implementation of 
front-ends for large software packages. 

This paper gives an overview of Yamm’s structure and design philosophy. Section 2 describes 
the menu configuration specification, a potentially user-specific description of an application’s menu 
structure(s) and terminal interface. Section 3 describes the Yamm routines usable by an application. 
The steps involved in implementing a program using Yamm are covered in Section 4, and an example 
tieing everything together follows in Section 5. 


2, MENU CONFIGURATION 

Applications running under the menu package consist of two parts: a description of the menu 
configuration (sometimes including terminal characteristics), which may be user-specific, and the body 
of application code, which includes a call to start up the menu package as well as calls to menu pack- 
age interface routines. 

The menu configuration is used at runtime to define the menu structure and any non-standard ter- 
minal characteristics; it may be read in from a programmer-specified file or included in the source. 
The example program in Section 5 uses both methods: if the menu configuration file ( menuconfig ) 
exists, the program uses it, otherwise it relies on the coded version. 

Menu configuration specifications are composed of menu and terminal definitions. 

Menu definitions define specific menus within the menu tree. Each definition contains the word 
MENU and a menu name, a series of prompt-name pairs, and an END. The name in each pair may be 
either a reference to an application function or the name of another menu defined within the menu 
configuration. 

Terminal definitions are optional and allow the user to specify non-standard keyboard mappings 
and terminal capabilities. Each definition contains the word TTY and a series of terminal types (e.g., 
vtlOO sun) followed by key and capability definitions. Key definitions specify a generic key-name 
(e.g., up_arrow, help), what the user calls the key to be used (e.g., go up, CTRL H), and the actual 
ASCII sequence generated by the key. For example: 

help:CTRL H:*H 

The redefinable keys are: 


up_arrow 

help 

enddataentry 

func_0 

func_4 

down_arrow 

root 

endselect 

func_l 

func_5 

right_arrow 

previous 

refresh 

func_2 

func_6 

left_arrow 

exit 

toggle 

func_3 

func_7 


Terminal capability definitions give the capability name and then the corresponding key sequence, as 
in: 


clear_screen::\033H\033J # ESC H ESC J - for VT52 

The redefinable terminal capabilities are: 


move set_inv_video reset_inv_video clear_screen 


PRECEDING PAGE BLANK NOT FILMED 


ifl M &■-> f wrrrnwwa fum 



Appendix G 




set_underline 

scroIl_region 

reset_gcs 

vert_bar 


reset_underline 

configure 

upper_left_cor 

lower_right_cor 


down_line 

reconfigure 

horiz_bar 

lower_left_cor 


clear_eoI 

set_gcs 

upper_right_cor 


Character sequences may be formed using the usual \octal-value (e.g., \033 for escape) and inserting 
the actual control or escape characters into the definition. The carat O may also be used to form 
easily-readable control characters. If system-special characters such as CTRL-C or CTRL-S are used, 
their normal functions are disabled inside the program. 

Null padding may be specified for terminal capability definitions by preceding the character sequence 
with the number of following nulls. For example, if the definition for clear_screen above required a 
following padding of 10 nulls, the sequence could be changed to 10\033H\033J. Neither type of ter- 
minal definition may be used in the menuconfig of a dynamically-created (nested) menu structure. 

Note that the formats for the move and scroll_region sequences are different from those used by 
termcap. Specifically, the values must come in the reverse of the default termcap order, and start at 1 
rather than 0. This simplifies integration of other terminals but may be confusing when compared with 
termcap entries. 

Comments and white space may be used freely within the menu configuration commands; see the 
example for more information. 


3. APPLICATION ROUTINES 

Here are the functions callable from application programs. Most of these return -1 on error and 
0 otherwise; see the example for information on actual usage. The structures and definitions used here 
are defined in menuapp.h. 

menu_start(config_name,config,func_table,localinit,localreinit,logfile) 
char *config_name; 
char *config[]; 

struct func_name_pair func_table[]; 
int (*localinit)(),(*localreinit)(); 

FILE *logfile; 

invokes the menu interface. It must be called before any of the other functions listed here. 
Config_name gives the name of the menu configuration file; this may be NULL if the 
configuration is hardcoded and no user override is to be permitted. Config gives a hardcoded 
default configuration; this may be NULL if there will always be a configuration file. 
Funcjable is a list of function name-code pairings; this is illustrated below. Localinit and 
localreinit point to functions invoked automatically when the specified menu tree is entered and 
left, respectively. Either or both of these may be NULL , but if they are used, should return -1 
on error and 0 otherwise. If session logging is desired, logfile should contain a file pointer to 
an open file. Otherwise it should be NULL. If logging is used, closing the file is left to the 
application. 


getpar(params,num_params,error_code,help_code) 
struct param *params; 
int num_params; 

int (*error_code)( ),(*help_code)( ); 


requests parameter values from the user using a data-entry screen. Params points to a series of 
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parameter definition structures, num _params contains the number of parameters defined, 
error_code points to a function able to detect errors or is NOECHK if none, and help_code 
points to a function which prints parameter information for the user on request or is NOHELP 
if none. 

Parameter definition is done using def( ), which is described below. 

The programmer-supplied error code receives three parameters: a pointer to the parameter 
definition structures, the number of the parameter to check, and the value supplied, an int- 
double-char * union. (Booleans are treated as integers for purposes of error checking.) Error 
checking functions typically use unspecified ( ), new_value( ), and unspecify( ), described below, 
to detect and correct errors. The function must return -1 if the parameter value is unaccept- 
able, and 0 otherwise. 

Help code receives two parameters: a pointer to the parameter definition structures, and the 
number of the parameter in question. One additional special case is also provided for. On 
entry into getpar( ), Yamm calls the help routine specifying parameter number -1 to enable out- 
put of any initial help or welcome message. This is illustrated in the example. 


def(params,param_num,prompt,type,value_ptr,...) 

struct param *params; 

int param_num; 

char ""prompt; 

int type; 

unsigned char *value_ptr. 


defines parameters on the data-entry screen. The first five parameters are required, in the order 
shown; subsequent parameters may come in any order and are optional, with appropriate 
defaults. 

params is the name of a block of storage reserved for parameters, as in struct param 
params[5]; to reserve space for five parameters, 

param_num is the number of the parameter being defined, starting with 0, 

prompt is a pointer to a short textual description of the value which will be used as a 
prompt string, 

type is the parameter type, INT, FLOAT, DOUBLE, STRING, or BOOL (YES/NO), and 

value _ptr is a memory location to receive the specified value(s). 

In addition, a variety of parameters may be defined by specifying a keyword followed by a 
comma and the relevant value(s): 

INCR precedes an increment in bytes from value_ptr to use when multiple values are 
specified - the default is parameter-type dependent: 4 for INT and FLOAT, 8 
for DOUBLE, 0 for STRING, and 4 for BOOL, 

WID precedes the field width in columns needed to specify the value - the default is 
parameter-type dependent: 6 for INT, 8 for FLOAT and DOUBLE, 20 for 
STRING, and 3 for BOOL, 
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COUNT precedes a pointer to an integer variable which will receive the number of 
values specified - the default is to not supply a count, 

LINE precedes the line location (where 0 is top of window) of the prompt - the default 
is 0, 

COL precedes the column location of the prompt (where 0 is the left edge) - the 
default is 0, 

DUP precedes the number of values expected, or the negative of the maximum number 
of values if the number is variable - the default is 1, 

DEFAULT indicates that the area referenced by the value_ptr parameter contains 
default values which should be displayed to the user - the default is "no 
default," 

GROUP precedes the group number (greater than or equal to zero) of the parameter; if 
the user specifies a value for any parameter within the group, all parameters 
must be specified and for tables, match in number of values - the default is 
"no group,” 

REQ indicates that a value for the parameter is required - the default is "not required," 

ENUM precedes two values, a number, and a pointer to that many values, from among 
which the user must choose in valuing the parameter, when the values are 
STRINGS (for STRING-type parameters), the pointer is to a list of pointers to 
these values, i.e., the list is defined: static char *legal_yalues[ ] = 

{"valuer rvalue!'',...); 

ENTRYLINE precedes the line number (starting with 0) of the first data-entry blank for 
this parameter - the default is to use the line number of the prompt, except 
when multiple data items are grouped together in a table format, in which case 
the default is the number of the line below the prompt, 

ENTRYCOL precedes the column number (starting with 0) of the first data-entry blank 
for this parameter - the default is that column to the right of the prompt, 
except when multiple data items are grouped together in a table format, in 
which case the default is the column number such that the prompt is centered 
over the column, and 

END functions as an end-of-definition keyword and is required. 

See the example for numerous parameter definitions. 


unspeci fied(param) 
int param; 

returns true if no value has been specified by the user for parameter param. This is most use- 
ful in the application-supplied error-checking routine, where it can be used to make sure that a 
specified value does not conflict with other related parameter values. This is typically used 
with new_value( ) and unspecifyl ) below. 
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new_value(params, entry) 
struct param *params; 
int entry; 

notifies the menu package that the value of the parameter numbered by entry has been 
changed, usually because of a change in the value of a related parameter. 


unspecify (param) 
int param; 

removes the value of the specified parameter. This is usually only useful inside error-checking 
routines, when a newly specified value is incompatible with the value of another parameter and 
the latter must be removed. 


create_new_subtree(config_name,config,func_table4ocalinitJocalreinit) 
char *config_name; 
char *config[]; 

struct func_name_pair func_table[]; 
int (*localinit)( ),(*localreinit)( ); 

dynamically creates a supplemental menu tree. The arguments are similar to the arguments for 
menu_start( ) above. The code pointed to by localinit will be executed immediately, and if 
executed without error (i.e., code returns 0) then the user will be placed at the root of the new 
menu tree. The function pointed to by localreinit is run on exit. Recursion is permissible with 
care, but the use of static variables should be avoided. 


4, TO IMPLEMENT A PROGRAM USING YAMM 
The following steps are sufficient to implement most programs using Yamm: 

1. Determine where the menu configuration file, if any, will be kept, and if desired, create a default 
configuration. Next, declare the functions which will be called through the menus and assign to 
each menu-callable function a name. Write any application-specific initialization and reinitializa- 
tion code. If logging is desired, fopen a file to contain the log. Finally, write the call to 
menu_start( ), using the data structures above as parameters. 

Example: 

char *config_name = ".Anenuconfig"; 

char *config[] = NULL; 

int functionl( ),function2( ),function3( ); 

struct func_name_pair funcs[]={ 

{functionl,"funcl"), 

{ function2,"func2" } , 

{function3,"func3"j, 

{0,’Vkeep last”), 

}; 


my_init( ) { /* application init code here */ } 
my_reinit() { /* reinit code here */ } 
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main() { menu_start(config_name,config,funcs,my_initjny_reinit,NULL); } 

2. Create a menu configuration file. An example for the above function table might be: 

MENU mainmenu 

DoFuncI/funcl # DoFuncl is the prompt; if chosen, calls fund. 

OtherFuncs/submenu 

END 

MENU submenu 

DoFunc2/func2 # func2 and func3 must be associated with a 

DoFunc3/func3 # function using a function table as above. 

END 

3. In each application routine called by the menus, define parameters using def( ), and write chk_ 
and help_ routines. (You may want to leave writing these routines until the application runs 
correctly. Use NOECHK and NOHELP in getpar( ) calls meanwhile.) 

4. Compile the application code, linking with the menu library and libtermcap.a. For example, 

cc mycode.c -o mycode -lyamm -Itermcap 

The resulting executable should display the menus as configured in your configuration file and 
allow you to execute the application functions. Once everything is working, you may want to 
change config_name and keep the file in a different place or keep the file contents exclusively in 
the code. 

5. AN EXAMPLE 

This section contains a detailed step-by-step implementation of a program using the menu pack- 
age. 


1. First create menuconfig: 

# This is the menu configuration file. Each menu consists of MENU with 

# the menu name, a number of menu entries, and an END; a menu entry is 

# made up of the text to display for the menu selection and the 

# function or submenu name, as appropriate. Terminal-specific 

# sequences and keystroke-function mappings start with the TTY keyword 

# and end with END. See the programmer documentation for more 

# specifics. Comments should be prefaced with a #; all such text is 

# ignored. Indentation may be used to illustrate menu structure. This 

# text may also be put into the code. SCCS yamm pro g g uide 4.22 - 7/12/88 

MENU mainmenu 
Info/information # function 
Two Legs/twolegs # submenu 
Four Legs/fourlegs # submenu 
END 

MENU twolegs 

Cockatiel/bird 

Parakeet/bird 
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Pigeon/bird 

END 

MENU fourlegs 

Alsatian/dog 

Collie/dog 

German Shepherd/dog 
END 

2. Add in the call to menu_start( ), defining the menu config filename and menu config, function 
table, local (re)initialization routines, and logging file pointer. Make sure you include menuapp.h 
where necessary. Compile the code, linking with the menu (-lyamm) library and libtermcap.a (- 
ltermcap). 

Here is the code from the demo program contained in demo.c: 

#ifndef lint 

static char sccsid[]="@(#)yamm_prog_guide 4.22 7/12/88"; 

#endif lint 

#include <ctype.h> 

#include <stdio.h> 

#include <strings.h> 

#include "menuapp.h" 

int informationO,dog(),bird(); 

char *config_name = "./menuconfig"; 
char *config[] = { 

"MENU mainmenu","Infonnation/information ,, , ,, Two Legs/twolegs”, 

"Four Legs/fourlegs","END", 

"MENU twolegs",”Cockatiel/bird","Parakeet/bird","Pigeon/bird","END", 

"MENU fourlegs","Alsatian/dog","Collie/dog","German Shepherd/dog" ."END", 

’’/keep last" 


struct func_name_pair func_table[]={ 
{ information, "information" } , 
{dog,"dog"}, 

(bird,"bird"}, 

{0,”/keep last"}, 


mainO 

{ 

FILE *logfile; 

logfile = fopen("demo.log","w"); 

(void)menu_start(config_name,config,func_table,(int (*)())NULL, 
(int (*)0)NULLJogfile); 

(void)fclose (logfile); 


informationO 

{ 


(void)printf("This is the Pets pet registry program. "); 
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(void)printf("Since this is for "); 

(void)printf("menu system demonstration only, no information is "); 
(void)printf(" actually saved. You are now at the top of a "); 
(void)printf(" short menu tree. By selecting menu entries "); 
(void)printf("(use the help key for more info) you can "); 
(void)printf("descend the tree in a manner compatible with your "); 
(void)printf("particular animal. "); 

(void)printf(”When you’ve reached the bottom of ”); 

(void)printf(”the menu tree, the function selected will display a ”); 
(void)printf("parameter "); 

(void)printf(’’entry screen. Feel free to move about the screen ”); 
(void)printf("(use the help key for specifics) "); 

(void)printf("and fill in values. If the program erases something "); 
(void)printf(" immediately after you’ve typed it, the input is "); 
(void)printf(’’illegal. "); 

(void)printf('Type the end-data-entry key "); 

(void)printf(’’when you’re done entering parameter values. Note that ”); 
(void)printf("the program may refuse to leave if some parameter "); 
(void)printf("value is required and unspecified. "); 

(void)printf("When you’ve reached the bottom of ”); 

(void)printf("the menu tree, the function selected will display a "); 
(void)printf("parameter "); 

(void)printf("entry screen. Feel free to move about the screen "); 
(void)printf("(use the help key for specifics) "); 

(void)printf("and fill in values. If the program erases something ”); 
(void)printf("immediately after you’ve typed it, the input is "); 
(void)printf(”illegal. ”); 

(void)printf(’Type the end-data-entry key ”); 

(void)printf(”when you’re done entering parameter values. Note that ”); 
(void)printf(”the program may refuse to leave if some parameter ”); 
(void)printf("value is required and unspecified. ’’); 


/* 

This function demonstrates the basic structure. Note that some values 
are statics. These are initialized to default values the first time, and 
then when this function is called in the future, the last values used are 
the defaults. Pet’s name goes into name (up to 20 characters), and is 
required; there is also a default. Foods takes up to 5 values, stored 
starting at location foods and every 20 bytes thereafter, the number of 
foods selected is returned in food_count. Eye color is simply a string, 
stored in eyes. The next two are boolean (YES or NO); note that booleans 
should always be initialized. The weights parameter illustrates how to 
request input of a matrix (in this case, a weights matrix for your dog). 

Note the use of the GROUP keyword (to enable table formation); this is 
somewhat awkward but very simple and flexible. The getpar request 
displays the menu and returns with the values, which in this example, are 
ignored. 

*/ 

dogO 

{ 

int chk_dog(),help_dogO,food_count; 

char name[25],foods[20*5]; 

static double size[2]; 
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static char eyes[20]; 

static int hcense=0,plays=0,first_time=l; 
static float wgts[9]; 
struct param params[9]; 

(void)strcpy(name,"Rover"); 
if (first_time) { 

(void)strcpy(eyes, "brown"); 
first_time=0; 

} 

(void)def(params,0, "Pet’s name", STRING, name, WID, 20,LINE,1, DEFAULT, REQ, 
END); 

(void)def(params.l, "Favorite food(s)", STRING, foods, WID, 15, INCR, 20, 

COUNT, &food_count, LINE, I , COL, 40, DUP, -5 END); 

(void)def(params,2,"Eye color" .STRING, eyes, WID, 10, LINE, 3, DEF AULT, REQ, 
END); 

(void)def(params, 3, "Licensed?", BOOL, &license, LINE, 5, DEFAULT.END); 
(void)def(params,4,"Likes to chase cars?", BOOL, &plays,LINE,7, DEFAULT, 
END); 

(void)def(params,5,"Ht, Length (fractional) ?",DOUBLE,size, 

WID, 10, LINE, 9,DUP, 2, REQ, END); 

(void)def(params,6, "Weights", FLOAT, wgts,INCR,sizeof(float) 1 ' , 3, LINE, 7, 

COL, 50, DUP, 3, GROUP, 0, ENTRYLINE, 8, ENTRYCOL.40JEND); 
(void)def(params, 7, "Weights”, FLOAT, wgts+l,INCR,sizeof(float)*3,LINE, 7, 
COL.50, DUP, 3, GROUP, 0, ENTRYLINE, 8, ENTRYCOL.50.END); 
(void)def(params,8, "Weights", FLOAT, wgts+2,INCR,sizeof(float)*3,LINE, 7, 

COL, 50, DUP,3, GROUP, 0, ENTRYLINE, 8, ENTRYCOL,60,END); 
if (getpar(params,9,chk_dog,help_dog) == -1) return; 

/* continue with rest of program here - there isn’t any in these examples */ 
(void)printf("%f %f0,size[0],size[ 1 ]); 


/* 

This is the error-checking routine for dog() above, which is very 
straightforward. Number is the number of the parameter, and value is the 
value specified (a union of three differently typed variables). If this 
returns a non-zero value, getpar will erase what the user typed, indicating 
that the input was erroneous. 

*/ 

/*ARGSUSED*/ 
chk_dog(paramsmumber, value) 
struct param *params; 
int number, 

union {int i; double f; char *s;} value; 

( 

int error, 

switch (number) { 

case 0: error = alphawhite(value.s); break; 
case 1; error = alphawhite(value.s); break; 
case 2: 

if ((error=color(value.s))!=0) { 

(void)printf("Unknown color. Use blue, gray, green "); 
(void)printf("or brown."); 

} 



break; 

default: error = 0; break; 

} 

retum(error); 

} 

/* 

This is the help routine for the dogO function above. When the user is 
entering parameter values and presses the help key, getpar passes the 
number of the parameter to this routine which prints the information 
desired. Also, the help function is called by getpar immediately on startup 
with a parameter value of -1 in case application has some specific prompt 
for user. 

*/ 

/*ARGSUSED*/ 
help_dog(params, number) 
struct param *params; 
int number, 

{ 

switch (number) { 

case - 1 : (void)printf("Welcome to the Dog menu"); break; 

case 0: (void)printf("Name of dog; the default is Rover"); break; 

case 1: (void)printf("Favorite foods”); break; 

case 2: (void)printf("Eye color”); break; 

case 3: (void)printf("Is your dog licensed?"); break; 

case 4: 

(void)printf("Do its ears peric up whenever it hears a VW? M ); 
break; 

} 

} 

/* 

This is somewhat more complicated than the previous function. Parameter 
2, and parameters 3 and 4 are mutually exclusive. (If a bird has its 
wings clipped, it cannot fly; if it can fly, its wings are not clipped.) 

This is enforced by chk_bird(). Also, if parameter 3 is specified, then 
parameter 4 must be, and vice versa; hence, they are specified as 
belonging to group 0 instead of NOGRP. This is enforced by the getpar 
routine. The first parameter illustrates the use of legal-value 
sets. Finally, if the third name is selected, the program dynamically 
creates another similar menu below the current one and goes into it 
This one contains no information option. 

*/ 

birdO 

{ 

int clipped=0,dist,chk_birdOdielp_birdO; 

float height; 

static char name[25]; 

static int first_time = 1; 

char units[20]; 

struct param params[5]; 

static char *poss_values[] = {"rover", "king" ."ohnooo!”}; 
static char *newconfig[] = { 

"MENU mainmenu'V'Two Legs/twolegs","Four Legs/fouriegs","END", 
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"MENU twolegs" , " Cockatiel/dog" , " Parakeet/dog" , "Pigeon/dog" , "END” , 
"MENU fourlegs","Alsatian/bird","Collie/bird", "German Shepherd/bird", 
"END", "/keep last" 

}; 

if (first_time) { 

(void)strcpy(name,"king M ); 
first_time = 0; 

} 

(void)def(params,0, "Pet’s name”, STRING, name, WID,20XINE,2,REQ,ENUM, 3, 
(unsigned char *)poss_values, DEFAULT, END); 

(void)def(params.l, "Height (fractional inches)", FLOAT.&height.WID, 6, 

LINE, 4, COL, 40, END); 

(void)def(params,2,"Wings clipped?", BOOL, &clipped, LINE, 4, DEFAULT.END); 
(void)def(params, 3, "Maximum flying distance (integer)”, INT, &dist,WID,4, 
LINE,8,GROUP,OJEND); 

(void)def(params,4,"Units" , STRING, units, WID.10XINE, 8, COL, 40, GROUP, 0, 
END); 

if (getpar(params,5,chk_bird,help_bird) == -1) return; 
if (strcmp(name,"ohnooo!") == 0) { 

(void)printf(" Ohnooo ! "); 

(void)create_new_subtree((char *)NULL,newconfig,func_table, 

(int (*)0)NULL,(int (*)0)NULL); 

} 

else (void)printf("What kind of name is 
/* continue with rest of program here - there isn’t any in these examples */ 

} 

/* 

Note in this function the handling at cases 2 through 4. If parameter 2 
becomes true (wings clipped), specified values for parameters 3 and 4 arc 
removed. Similarly, if parameter 3 or 4 is given a value, then parameter 
2 is cleared. This is done using unspecify, which removes the value for 
the specified parameter, and new_value, which tells the menu package that 
the error routine has changed a value and it should be redisplayed. 

*/ 

/*ARGSUSED*/ 

chk_bird(params,number,value) 
struct param *params; 
int number, 

union {int i; double f; char *s;} value; 

{ 

int error,i,pr_msg; 
char locbuf[30]; 
switch (number) { 

case 0: error = alphawhite(value.s); break; 
case 1: 

error = (value.f<2. II value.f>15.? -1:0); 
if (error == -1) 

(void)printf("Birds must be between 2 and 15 inches tall."); 
break; 
case 2: 
error = 0; 
pr_msg = 0; 

if (value.i && !unspecified(3)) { 
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(void)unspecify(params,3); 

pr_msg=l; 

} 

if (value.i && !unspecified(4)) { 

(void)unspecify(params,4); 

pr_msg=l; 

} 

if (pr_msg) 

(void)printf("Changing flying distance to be undefined."); 
break; 
case 3: 

error= (value.i<0? -1:0); 

if (error == 0 && !unspecified(2) && *((int *)params[2].value)) { 
*((int *)params[2J.value) = 0; /* or clipped=0; */ 
(void)new_value(params,2); 

(void)printfC' Changing wings to 

} 

break; 
case 4: 
error = 0; 

(void)strcpy(locbuf.value.s); 
for (i=0;i<strlen(locbuf);i++) 

if (isupper(locbuf[i])) locbuf[i]+=32; 
if (strcmp(locbuf,"inches")!=0 && strcmp(locbuf,"feet")!=0 && 
strcmp(locbuf," yards") ! =0 && strcm pQocbuf, "miles") ! =0) 
error = -1; 
if (error = -1) 

(void)printf("Please use inches, feet, yards, or miles."); 
else if (!unspecified(2) && *((int *)params[2].value)) { 

*((int *)params[2].value) = 0; /* or clipped=0; */ 
(void)new_value(params,2); 

(void)printf("Changing wings to 

} 

break; 

default: error = 0; break; 

} 

retum(error); 

} 

/♦ARGSUSED*/ 
help_bird(params,number) 
struct param *params; 
int number, 

{ 

switch (number) { 

case 0: (void)printf("Name of bird."); break; 

case 1; (void)printf("Height, between 2 and 15 inches"); break; 

case 2: (void)printf("Are wings clipped?"); break; 

case 3: 

(void)printf("Maximum flying distance. "); 

(void)printf("If this is specified, distance units must also "); 
(void)printf("be specified and vice versa."); 
break; 
case 4; 
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(void)printf("Distance units. "); 

(void)printf("If this is specified, maximum flying distance "); 
(void)printf("must also be specified and vice versa."); 
break; 

} 

} 

/* 

Error checking routines: 

alphawhite(buf) returns 0 iff buf is only letters and white space 
color(buf) returns 0 iff buf is a valid color 

*/ 

alphawhite(buf) 
char *buf; 

{ 

int i; 

for (i=0;i<strlen(buf);i++) 

if (!isalpha(buf[i]) && !isspace(buf[i])) retum(-l); 
retum(O); 

} 

colorfbuf) 
char *buf; 

{ 

int i; 

char locbufI30]; 

(void)strcpy(locbuf.buf); 

for (i=0;i<strlen(locbuf);i++) if (isupper(locbuf[i])) locbuf[i]+=32; 
if (strcmp(locbuf,"brown")==0 II stremp(locbuf,"blue")==0 II 

strcmp(locbuf,"green")==0 II strcmp(locbuf,"gray")==0) retum(O); 
else retum(-l); 

} 


6. INTERNALS 

There are a few internals issues that a programmer should be aware of. 

Yamm changes the handling of stdout and stderr in order that program output can be intercepted 
and properly placed in the menu windows. In the unlikely event of a bug in the output handling rou- 
tines, traces and other output statements might not function correctly. To bypass this processing, the 
file pointer mm_termfp may be referenced using extern ; this pointer directly accesses the screen. 

Also, Yamm starts up a subprocess (menuwatch) and allocates a semaphore in order to properly 
handle application I/O. Otherwise application I/O would be limited to 4096 bytes (the size of the 
buffered I/O buffer) and flushed only on application completion. The subprocess waits for application 
I/O and then signals Yamm to print it in the proper place. Normally, when an application dies, the 
subprocess will also die, freeing the semaphore in the process. However, if the subprocess is killed, 
the semaphore may not get removed; when enough semaphores build up, Yamm will not start properly. 
To avoid this, the user should never kill the subprocess explicitly. If semaphores are left around, 
ipcrm(l) may be used to remove them. 

In order to dump the screen, Yamm creates a temporary file in the user’s current directory and 
then attempts to troff this file using the pipeline tbl I ptroff -ms. If this succeeds, the file is then 
deleted; otherwise the file remains. The user may specify an alternative command (or no command) by 
setting the environment variable MENU_HARDCOPY_CMD. For example, the command setenv 
MENU_HARDCOPY_CMD ’tbl %s I ptroff -ms’ would print hardcopies without deleting the originals. 
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The names of temporary files are determined by the day and time of the screen dump; e.g., menu- 
pic 109 1252 was dumped Monday (1), at time 9:12:52. 
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Subroutine: main(argc, argv) 

File: main.c 

Input: int argc 

char *argv[] 

Output: none 

Function: This is the main program for Cipetool. It calls some initialization routines and then 

calls window_main_loop which is the Sunview dispatcher. Window_main_loop will re- 
turn when the user clicks on the "quit" button. Currently, main does not use any argu- 
ments. 

Suggested Modification: 

An argument should be used to indicate which version of CIPE to run. This would 
make it convenient to use a new version of CEPE. 

Subroutine: Notify_value wait3_handler(me, pid, status, rusage) 

File: support.c 

Input: int ‘me 

int pid 

union wait ‘status 
struct rusage ‘rusage 

Output: none 

Function: This function will be called by the dispatcher if the CIPE command line interpreter dies. 

When this happens, Cipetool will print an error message and exit. 

Suggested Modification: 
none 

Subroutine: button_pressed(item, event) 

File: support.c 

Input: Panel Jtem item 

Event *event 

Output: none 

Function: This routine will be called whenever the user clicks on one of the buttons. It checks to 

see which button was pressed and calls the appropriate routine to handle it. 

Suggested Modification: 
none 
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Subroutine: type_text(window, event, arg) 

File: support.c 

Input: Window window 

Event *event 
caddr_t arg 

Output: none 

Function: This routine will be called whenever the user types in the text window connected to 

CEPE. It will send the character that the user typed to CIPE. 

Suggested Modification: 

This is not dealt with correctly right now. You can send information to CIPE this way, 
but Cipetool will get confused when CIPE responds. This should be fixed so that the 
user can use Cipetool both as an icon-based tool and a Cli-based tool. 

Subroutine: list_functions(event) 

File: support.c 

Input: Event *event 

Output: none 

Function: This is a very short routine that gets called whenever the user clicks on the "functions" 

button. It does a menu_show of the functions menu. 

Suggested Modification: 

This routine really doesn’t need to exist. The call to menu_show could be moved up 
into button_pressed. 

Subroutine: Notify_value frame_event_handler(win, event, arg) 

File: windows.c 

Input: Window win 

Event *event 
caddr_t arg 

Output: none 

Function: This is the event handler for the Cipetool frame. 

Suggested Modification: 
none 

Subroutine: init_windows( ) 

File: windows.c 

Input: none 

Output: none 

Function: This routine is called to initialize all of the startup windows. It creates all of the buttons 

as well. 

Suggested Modification: 
none 



CDPETOOL 


H-5 


Subroutine: struct symtab_type *window_under_cursor(x, y) 

File: windows.c 

Input: int x 

int y 

Output: none 

Function: This routine returns a pointer to a symbol which is the window under the cursor. Nor- 

mally this will be an image window or a function window. 

Suggested Modification: 
none 

Subroutine: connect_wins(start_win, start_x, start_y, end_win, end_x, end_y) 

File: windows.c 

Input: Window start_win 

int start_x 
int start_y 
Window end_win 
int end_x 
int end_y 

Output: none 

Function: This routine will draw a line between two windows. 

Suggested Modification: 

This routine should be called whenever one of the the windows is moved. It is only 
called once, currently, but this means that you have lines drawn to nowhere if you move 
a window. 

Subroutine: void draw_main_canvas(canvas, pixwin, repaint.area) 

File: windows.c 

Input: Canvas canvas 

Pixwin *pixwin 
Rectlist *repaint_area 

Output: none 

Function: Draw_main_canvas draws the frame buffer area onto the Cipetool canvas. 

Suggested Modification: 
none 
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Subroutine: in_frame_buffer 

File: windows.c 

Input: int x 

int y 

Output: none 

Function: This routine will return a 1 if the x and y positions passed are within the frame buffer 

area of the Cipetool canvas and a 0 otherwise. It is assumed that x and y are relative to 
that canvas. 

Suggested Modification: 
none 

Subroutine: init_symtab( ) 

File: symtab.c 

Input: none 

Output: none 

Function: Init_symtab should be called before any other symbol table routine is called. It initial- 

izes the hash table of symbols. The hash table has header cells to make insertion and 
deletion from the symbol table easier. 

Suggested Modification: 
none 

Subroutine: hash(name) 

File: symtab.c 

Input: char *name 

Output: none 

Function: This routine returns the bin number where "name” should be stored or retrieved. The 

current hashing functions are the sum of the squares of the ASCII values of "name.” 

Suggested Modification: 
none 

Subroutine: struct symtab_type *add_symbol(name) 

File: symtab.c 

Input: char *name 

Output: none 

Function: This routine creates a new symbol table entry for name and returns a pointer to that en- 

try. It initializes some of the fields in the entry. 

Suggested Modification: 
none 
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Subroutine: struct symtab_type *find_symbol(name) 

File: symtab.c 

Input: char *name 

Output: none 

Function: Given the name of a symbol, this function returns a pointer to the entry for that symbol. 

If there is no such symbol then a NULL is returned. 

Suggested Modification: 
none 

Subroutine: deIete_symbol(name) 

File: symtab.c 

Input: char *name 

Output: 

Function: Delete_symbol will delete the symbol name from the symbol table. If there are multiple 

entries for name, only the first one will be removed. The current implementation does 
not ever have multiple entries, but this assumption is not made in any of the symbol 
table routines. 

Suggested Modification: 
none 

Subroutine: char *unique_constant_symbol() 

File: symtab.c 

Input: none 

Output: none 

Function: This function returns a string which is guaranteed not to exist in the symbol table. 

Currently, this is done by appending a number to the string "constant " The number is a 
static that gets incremented on each call to this routine. A check is made to see if this 
symbol is in the symbol table. If it is, then the static will be incremented until this 
check fails. 

Suggested Modification: 
none 

Subroutine: char *unique_image_symbol( ) 

File: symtab.c 

Input: none 

Output: none 

Function: This routine functions like unique_constant_symbol but it appends the number to the 

string "image.” 

Suggested Modification: 
none 



H-8 


Appendix H 


Subroutine: 

File: 

Input: 

Output: 

Function: 


struct param_type *new_params( ) 

symtab.c 

none 

none 

This function is called by the parser for the functions file. It gets called whenever the 
parser encounters an argument list. It initializes the empty parameter structure and re- 
turns it. 


Suggested Modification: 
none 


Subroutine: 

File: 

Input: 

Output: 

Function: 


struct param_type *add_param(params) 

symtab.c 

struct param_type *params 
struct param_type *params 

This routine adds another parameter to the end of params and returns a pointer to this 
new entry. It will be called by the parser to add another argument to a parameter list. 
This routine does not fill in the parameter structure. This needs to be done by the call- 
er. 


Suggested Modification: 
none 


Subroutine: 

File: 

Input: 

Output: 

Function: 


yyparse( ) 
rc.y 
none 
none 

This routine is generated by the UNIX utility YACC. It is the parser used to parse the 
file declaring all of the available application functions and their arguments and return 
values. A LALR description of the language is in the file rc.y. 


Suggested Modification: 

This version of the parser is incompatible with Alan Mazer’s version now. This implies 
that some of the function definition files used by Alan will not work with Cipetool. 
This needs to be fixed. 


Subroutine: 

File: 

Input: 

Output: 

Function: 


yyerror(s) 

rc.y 

char *s 

none 

This function is called by the parser whenever an error is encountered while parsing the 
function definition file. It prints the string on stderr along with the line number of the 
offending command. 


Suggested Modification: 
none 
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Subroutine: yylex 

File: rclex.l 

Input: none 

Output: none 

Function: This is the lexical analyzer for the function definition file. It is called by yyparse when- 

ever a new token is desired. 

Suggested Modification: 
none 

Subroutine: print_tabs(level) 

File: name_list.c 

Input: int level 

Output: none 

Function: This routine is mainly for debugging. It is called by print_files to print out level tabs. 

Suggested Modification: 
none 

Subroutine: print_files(files, level) 

File: name_list.c 

Input: struct name_list_type *files 

int level 

Output: none 

Function: This routine is used for debugging. It prints out files with each directory level being in- 

dented one more tab than the previous level. 

Suggested Modification: 
none 

Subroutine: char *basename(name) 

File: nameJisLc 

Input: char *name 

Output: none 

Function: This routine returns a pointer to the basename of the filename it is called with. A files 

basename is the last part of the filename after any ’/’s. For instance, 
basename("/ufs/images/girl.bw") is "girl.bw." 

Suggested Modification: 

This routine returns a pointer into the argument, which can lead to some strange results 
sometimes. It might be better for this to be changed. 
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Subroutine: struct name_list_type *getjmage_files(filename) 

File: name_list.c 

Input: char ’filename 

Output: none 

Function: This function reads in all of the image files in the directory filename or its children. It 

reads each file in the directory to see if it has a corresponding image header file. If it 
does, then it adds it to its list of image files. 

Suggested Modification: 
none 

Subroutine: length_name_list(list) 

File: name_list.c 

Input: struct name_list_type ’list 

Output: none 

Function: This function returns the number of elements in a name list. 

Suggested Modification: 
none 

Subroutine: print_name_list(list) 

File: name_list.c 

Input: struct_namejist_type ’list 

Output: none 

Function: This function prints all of the elements of a name list. 

Suggested Modification: 
none 

Subroutine: sort_nameJist(list) 

File: namejistc 

Input: struct name_list_type ’list 

Output: none 

Function: This routine uses a quick sort to sort the members of a name list in ASCII order. Note 

that this routine sorts by moving pointers in the list around. So any pointers into the 
middle of the name list before the sort will probably be invalid after the sort. 

Suggested Modification: 
none 
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Subroutine: mystrcmp(pl, p2) 

File: namejist.c 

Input: struct name_list_type **pl 

struct name_list_type **p2 

Output: none 

Function: This routine just contains a call to strcmp with the name field of the namejist. It is 

called by the quicksort in sort_name_list. 

Suggested Modification: 
none 

Subroutine: add_function(name) 

File: name_list.c 

Input: char *name 

Output: none 

Function: This routine adds a function to the list of functions in the global functionsjist. This 

list is used to create the functions menu. 

Suggested Modification: 
none 

Subroutine: init_images( ) 

File: images.c 

Input: none 

Output: none 

Function: This routine is responsible for doing any initialization of image structures. It should be 

called before any of the other functions in images.c. For now, it just initializes the glo- 
bal variable image_canvases, which is a list of all of the canvases associated with im- 
age icons. 

Suggested Modification: 
none 

Subroutine: load_images(image_menu, files) 

File: images.c 

Input: Menu image_menu 

struct name_list_type *files 

Output: 

Function: ' This routine takes a name list of files and builds a menu out of it If the name list has 

several levels, i.e., it represents several directory levels, then the menu will have several 
levels with pullright menus representing the different levels. 

Suggested Modification: 
none 
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Subroutine: 

image_selected(menu, item) 

File: 

images.c 

Input: 

Menu menu 
Menu_item item 

Output: 

none 

Function: 

This routine will be called by the dispatcher whenever the user selects an image from 
the image menu. It will figure out which image was selected, create a symbol name for 
that image, and send a command to CIPE to read in that image. Once it has done this it 
calls drawjmage to draw an iconic representation of this image. 

Suggested Modification: 
none 

Subroutine: 

struct image_header_type *get_image_header(filename) 

File: 

images.c 

Input: 

char *filename 

Output: 

none 

Function: 

This routine will return the CIPE header for those files that CIPE knows about. For 
now it looks for a file that ends in .hdr. It first appends .hdr to the filename, and if this 
fails it searches for basename(filename).hdr, where basename is the filename without the 
suffix. For example, if the filename is cheryl.red and there is no cheryl.red.hdr then 
cheryl.hdr will be opened if it exists. 

The header is ASCII so it is humanly readable and writable. If the .hdr file does not 
contain a valid CIPE header, or does not exist, then a NULL pointer is returned. 

Suggested Modification: 

In the future, this routine will probably be replaced with one that searches a database for 
the headers. 

Subroutine: 

skip_blanks(fp) 

File: 

images.c 

Input: 

FILE *fp 

Output: 

none 

Function: 

This routine is not called by anyone. 

Suggested Modification: 

Get_image_header should call this routine to allow spaces between the key words. 
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Subroutine: put_image_header(filename, header) 

File: images.c 

Input: char *filename 

struct image_header_type *header 

Output: none 

Function: This routine will return the CEPE header for those files that CIPE knows about. For 

now, it looks for a file that has ,hdr appended to the original file name and reads the 
header out of there. The header is ASCII so it is humanly readable and writable. If the 
.hdr file does not contain a valid CIPE header, or does not exist, then a NULL pointer is 
returned. 

Suggested Modification: 
none 

Subroutine: showjmage(name) 

File: images.c 

Input: char ‘name 

Output: none 

Function: This routine is not called by anyone any more. It displays a single band of an image on 

the screen. This routine was used during debugging. It still exists because it may be of 
some use at some later date. 

Suggested Modification: 
none 

Subroutine: function_se!ected(menu, item) 

File: functions.c 

Input: Menu menu 

Menu Jtem item 

Output: none 

Function: This function is called by the dispatcher when the user selects a function from the func- 

tions menu. It figures out which function was selected and then calls draw_function to 
draw an icon of it. 

Suggested Modification: 
none 

Subroutine: init_functions( ) 

File: , functions.c 

Input: none 

Output: none 

Function: This routine is responsible for initializing the functions menu. It calls routines to read 

and parse the users .cipetoolrc so that it knows what functions are available. 

Suggested Modification: 
none 
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Subroutine: build_functions_menu( ) 

File: functions.c 

Input: none 

Output: none 

Function: Once the list of functions as been created by the parser, build_functions_menu will 

create the menu to hold them all. 

Suggested Modification: 

The current implementation may look unusual if there are over 50 functions. 

Subroutine: Notify_value function_event_proc(win, event, arg) 

File: functions.c 

Input: Window win 

Event *event 
caddr_t arg 

Output: none 

Function: This routine will be called whenever the user clicks the mouse while over a function 

icon. If the button is the left button, then this event will signal the beginning or end of 
the connection of two functions. If it is the beginning, it sets a global indicating this, 
otherwise it draws a line between the two windows. 

Suggested Modification: 

This routine should never be called. All windows now have the same event handler, 
namely button_in_window. 

Subroutine: draw_function(name) 

File: functions.c 

Input: char ‘name 

Output: none 

Function: Draw_function draws the icon for a specific function. It creates the frame and canvas 

for it and then draws in the boxes and labels indicating parameters and return values. 

Suggested Modification: 
none 

Subroutine: struct param_type *nearest_parameter(symbol, xpos, ypos) 

File: functions.c 

Input: struct symtab_type ♦symbol 

int xpos 
int ypos 

Output: none 

Function: Given a symbol and a mouse position, this routine will return a pointer to the nearest 

parameter. 

Suggested Modification: 
none 
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Subroutine: type_of_result(s) 

File: functions.c 

Input: char *s 

Output: none 

Function: This routine is called after a function has been sent to CIPE and we are waiting for the 

results. It determines the type of the result and draws the corresponding icon. For in- 
stance if "filter" is called, it will return an image. Type_of_resuIt will determine this 
and draw an icon for that image. 

Suggested Modification: 

This routine needs to be fixed so that it does not get confused so easily. It also needs to 
take care of other types besides images. This may be a lower priority, because most of 
our tools return images. 

Subroutine: error(string) 

File: error, c 

Input: char *string 

Output: none 

Function: This function pops up a window with a given message on it (usually an error message) 

for a given number of seconds and then removes it The number of seconds that the 
message stays up is given by the global error_on_screen. This is implemented rather 
strangely. The window is displayed and an alarm is set to go off after so many seconds. 
That alarm will call error_off which will get rid of the window. 

Suggested Modification: 

In Sunview I in SunOS 4.0, there is a new class of windows called alerts. Error should 
be rewritten to use this class. 

Subroutine: Notify_value error_off(me, which) 

File: error.c 

Input: Notify_client me 

int which 

Output: none 

Function: This routine deletes the error window. It is used in conjunction with error above. 

Suggested Modification: 
none 
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Subroutine: Notify_value button _in_window(win, event, arg) 

File: draw_image.c 

Input: Window win 

Event *event 
caddr_t arg 

Output: none 

Function: This function is called whenever the mouse is clicked in a window. It is responsible for 

determining the type of the window (image, function, or constant) and doing whatever is 
necessary. Most of the time a left click will be used to indicate the beginning or end of 
a line between a function and its arguments. 

Suggested Modification: 
none 

Subroutine: draw_image(image_name, image_header) 

File: draw_image.c 

Input: char *image_name 

struct image_header_type *image_header 

Output: none 

Function: This routine will draw the iconic representation of an image. The icon is proportional to 

the height and width of the image. 

Suggested Modification: 

Currendy, only two dimensional images are supported. The current plan is to have a 
scrollbar-like object that allows you to select particular bands. Currendy, selecting a 
subsection of the image is not supported either. This will be done by clicking a mouse 
button at the desired upper left comer and dragging to the desired lower right comer. 

Subroutine: which_band_proc(item, value, event) 

File: draw_image.c 

Input: Paneljtem item 

int value 
Event *event 

Output: none 

Function: This routine determines which band has been selected using the scrollbar. It is not 

called at the current time but will probably be called when multiband images are sup- 
ported. 

Suggested Modification: 
none 
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Subroutine: constant_window( ) 

File: constants 

Input: none 

Output: none 

Function: This routine creates a window into which the user can enter a constant. When the 

number is entered, the window will change shape to exactly fit the constant. If the con- 
stant is a string, then it should be surrounded by double quotes. 

Suggested Modification: 
none 

Subroutine: PaneLsetting constant_entered(item, event) 

File: constants 

Input: Paneljtem item 

Event ‘event 

Output: none 

Function: When the user types a key in a constant window, this function gets called by the 

dispatcher. It determines if the key is valid and echos it in the window if it is. It also 
checks for the end of the input (a carriage return) and resizes the window appropriately. 

Suggested Modification: 
none 

Subroutine: array_window( ) 

File: array.c 

Input: none 

Output: none 

Function: This routine creates a window into which the user can enter an array. When the ele- 

ments are entered, the window will change shape to exactly fit the array. 

Suggested Modification: 

There is no way to enter two-dimensional arrays. The correct method has not been 
determined. 

PaneLsetting array_entered(item, event) 
array.c 

Paneljtem item 
Event ‘event 

Output: none 

Function: When the user types a key in an array window this function gets called by the dispatch- 

er. It determines if the key is valid and echos it in the window if it is. It also checks 
for the end of the input (a carriage return) and resizes the window appropriately. 

Suggested Modification: 
none 


Subroutine: 

File: 

Input: 
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Subroutine: get_results_routine(func) 

File: cipe_comm.c 

Input: int (*func)() 

Output: none 

Function: This routine sets up the function that will be called whenever the results from a com- 

mand are received. The function will be called with a ptr to a string containing the line 
received. When the command is finished (i.e., the ’> * prompt is received) the function 
will be called once more with a NULL pointer. The function should use this as a signal 
to clean up. 

Suggested Modification: 
none 

Subroutine: Notify_value read_pipe(me, fd) 

File: cipe_comm.c 

Input: int ♦me 

int fd 

Output: none 

Function: This function is called by the dispatcher whenever there is data available on the pipe 

connected to CEPE. It reads the pipe, echos it to the CIPE window and calls any func- 
tions that have been set to handle the input. 

Suggested Modification: 

Read_pipe gets confused when CIPE returns unsolicited input. Currently, any output 
from an application will cause it to lose track of its current state. This should be fixed. 

Subroutine: sub_proc(proc_name, argv, send, receive) 

File: cipe_comm.c 

Input: char ♦proc_natne 

char *argv[] 
int *send 
int *receive 

Output: none 

Function: This function will fork a process with two pipes connected to it. One is attached to the 

stdin of the forked process and one to the stdout. These two fd’s will be returned in 
send (attached to stdin) and receive (attached to stdout). The process id (pid) of the 
forked process will be returned. If something went wrong (could not fork process or 
could not exec) then -1 is returned. 

Suggested Modification: 
none 
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Subroutine: send_string(s) 

File: cipe_comm.c 

Input: char *s 

Output: none 

Function: This procedure is used to send a string to CIPE. 

Suggested Modification: 

Calls to this routine should probably be replaced with calls to fputs. 

Subroutine: init_comm( ) 

File: cipe_comm.c 

Input: none 

Output: none 

Function: This routine will initialize communication with CIPE. It creates a child remote shell 

(rsh) process to the hypercube host to run CIPE and sets up file pointers to communicate 
with it. File descriptors could have been used, but they are not nearly as convenient. 

Suggested Modification: 
none 
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/* cipedict version 2.1 7/25/88 */ 

function filter(input "In", input "Box width”, input "Box height", input "Wgts", 
input "Loadtype”) 

returns "Out” pathname "/ufs/cipe/appl/cp/cpfilter" 
function geom(input "In", input "Tiepoints filename”) 
returns "Out" pathname "/ufs/cipe/appl/cp/cpgeom" 
function size(input "In", input "Line zoom", input "Sample zoom”) 
returns "Out" pathname "/ufs/cipe/appl/cp/cpsize” 
function clearO 

returns "Out" pathname ”/ufs/cipe/appl/cp/clear" 


PRECEDING PAGE BLANK NOT FILMED 


tm 'V' 
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/* builtin.h version 2.1, 7/25/88 */ 

#ifftdef BUILTIN.H 
#define BUILTIN.H 


/* function name definition */ 


#define LESS_THAN_FUNCTION 1 

#define LESS_THAN_EQUAL_FUNCTION 2 
#define EQU AL_FUNCTION 3 

#define N OT.EQU AL_FUNCTION 4 

#define GREATER_THAN_FUNCTION 5 

#define GREATER_THAN_EQUAL_FUNCTION6 
#define AND_FUNCTION 7 

#define OR.FUNCTION 8 

#define BITAND.FUNCTION 9 

#define BITOR_FUNCTION 10 

#define BITXOR_FUNCriON 11 

#define PLUS_FUNCTION 12 

#define MINUS_FUNCTION 13 

#define M ULT_FUN CTION 14 

tdefine DIV_FUNCTION 15 

#endif BUILTIN.H 
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/* cipe.h version 2.2, 8/23/88 */ 

#ifndef CIPE_H 
#define CIPE_H 


struct image_h { 

char header_indicator[5]; 
int datatype, 
nl, 


}; 


ns, 

nb, 

offset; /* offset in bytes where data starts. */ 

float swl, 
ewl; 

/* used to skip headers. */ 
unsigned char reserved[32]; 

struct image_header_type *next; /* for use when images */ 

/* are in a linked list. */ 


#define CIPENAMESIZE 80 

typedef char cipe_file_name[CIPENAMESIZE]; 

typedef char cipe_sym_name[CIPENAMESIZE]; 

#include "symbol.h" 

#include "funclib.h" 

/* general constants */ 

tifndef TRUE 
#define TRUE 1 

#define FALSE 0 

#endif TRUE 

#define OFF 0 
fdefine ON 1 

#define IVAS_UNIT_NUM 0 
fdefine RASTER_UNTT_NUM 1 

extern int docjiproc; 

/* system attributes */ 

struct attr_def { /* */ 

char *name; /* mods to this section must also be in cipeappl.h! */ 

int value_type; /* */ 

int value; 
int access; 

}; 


#define COPROCESSOR.ATTR 
#define CUBE_DIMENSION_ATTR 


0 

1 
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tdefine DISPLAY_DEVICE_ATTR 2 

tdefine MOUSE_ATTR 3 

#define LOGGING.ATTR 4 

#define DEB UG_LEVEL_ATTR 5 

#define LEX_TRACE_ATTR 6 

tdefine PARSE_TRACE_ATTR 7 

#define CODEGEN_TRACE_ATTR 8 

#define EXEC_TRACE_ATTR 9 

#deflne SYMTAB_TRACE_ATTR 10 

#define FUNCTAB_TRACE_ATTR 11 

#define CUBE_COMMAND_TRACE_ATTR 12 
#define CUBE_DATA_TRACE_ATTR 13 

tdefine CUBE_SYMBOL_TRACE_ATTR 14 

#define APPL_TRACE_ATTR 15 

tdefine MENU_MODE_ATTR 16 

tdefine NUM_ATTRS 17 


extern struct attr_def cipe_attr[]; 


tdefine COPROCESSOR 
tdefine CUBE.DIMENSION 
tdefine DISPLAY_DEVICE 
tdefine MOUSE 
tdefine LOGGING 
tdefine DEB UG_LE VEL 
tdefine LEX_TRACE 
tdefine PARSE_TRACE 
tdefine CODEGEN_TRACE 
tdefine EXEC_TRACE 
tdefine S YMT AB_TRACE 
tdefine FUNCTAB.TRACE 
tdefine CUBE_COMMAND_TRACE 
tdefine CUBE_DATA_TRACE 
tdefine CUBE_SYMBOL_TRACE 
tdefine APPL_TRACE 
tdefine MENU_MODE 


cipe_attr[COPROCESSOR_ATTR] .value 
cipe_attr[CUBE_DIMENSION_ATTR].value 
cipe_attr[DISPLAY_DEVICE_ATTR].value 
cipe_attr[MOUSE_ATTR].value 
cipe_attr[LOGGING_ATTR].value 
cipe_attr[DEBUG_LEVEL_ATTR].value 
cipe_attr[LEX_TRACE_ATTR] .value 
cipe_attr[PARSE_TRACE_ATTRl .value 
cipe_attr[CODEGEN_TRACE_ATTR] .value 
cipe_attr[EXEC_TRACE_ATTR].value 
cipe_attr[SYMTAB_TRACE_ATTR] .value 
cipe_attr[FUNCTAB_TRACE_ATTR] .value 
cipe_attr[CUBE_COMMAND_TRACE_ATTR] .value 
cipe_attr[CUBE_DATA_TRACE_ATTR] .value 
cipe_attr[ CUB E_S YMB OL_TRACE_ ATTR ] .value 
cipe_attr[APPL_TRACE_ATTR].value 
cipe_attr[MENU_MODE_ATTR] .value 


tdefine ALL 0 

tdefine INTERNAL 1 


/* keyword values */ 

struct keyword_value_def { 
char *name; 
int attribute; 

}; 


tdefine NOCOPROCESSORJCWD 0 
tdefine CUBEJCWD 1 

tdefine GAPPJCWD 2 

tdefine NODISPLAYDEVICE_KWD 3 
tdefine IVAS_KWD 4 

tdefine RASTER.KWD 5 
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#define NUM_KEYWORD_VALUES 6 
extern char *bools[]; 

extern struct keyword_value_def keyword_values[]; 

/* session logging */ 

#define printf cipe_printf 
#define fgets cipe_fgets 
#define gets(a) cipe_fgets(a,80,stdin) 
extern char *cipe_fgets(); 
extern int cipe_printfO; 
extern int session_log_num; 

extern FILE *session_log; 

/* code segments */ 

struct code_seg_def { 
char *name; 
struct instruction *code; 
struct cipe_symbol *symbols; 
struct cipe_fimction * functions; 
unsigned int code_lengthjnax_code_length; 
unsigned int stail,ftail,max_stail,max_ftail; 
unsigned char workspace; 
struct code_seg_def ^previous; 

}; 


extern struct code_seg_def *code_seg; 

/* setjmp/longjmp */ 

#include <setjmp.h> 

extern jmp_buf orig_env; 

#endif CIPE_H 

/* installation-dependent defs */ 

#define dPE_DICTIONARY "/spacely/ufs/cipe/include/cipedict" 
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/* cipeappl.h version 2.1, 7/25/88 */ 

fifndef CIPEAPPL_H 
#define CIPEAPPL..H 


#include <local/menuapp.h> 
#include "symbol.h" 
#include "elt_data.h" 


extern struct { 
char *name; 
int value_type; 
int value; 
int access; 

} cipe_attr[]; 


fdefine COPROCESSOR_ATTR 0 

#define CUBE_DIMENSION_ATTR 1 

#define MOUSE_ATTR 3 

fdefine DEB UG_LEVEL_ATTR 5 

fdefine APPL_TRACE_ATTR 15 

fdefine MENU_MODE_ATTR 16 


fdefine COPROCESSOR 
fdefine CUBE_DIMENSION 
fdefine MOUSE 
fdefine DEB UG_LEVEL 
fdefine APPL_TRACE 
fdefine MENU_MODE 


cipe_attr[COPROCESSOR_ATTR].value 
cipe_attr[CUBE_DIMENSION_ATTR].value 
cipe_attr[MOUSE_Arrk]. value 
cipe_attifDEBUG_LEVEL_Al'Ik].value 
cipe.attil APPL.TRACE.ATTR] .value 
cipe_attr[MENU_MODE_ATTR] .value 


fdefine CIPENAMESIZE 80 

typedef char cipe_file_name[CIPENAMESIZE]; 

typedef char cipe_syra_name[CIPENAMESIZE]; 


/* cli related definitions */ 

extern symbolnum cipe_docall_args[]; 

extern symbolnum cipe_docall_result; 


fdefine NOK 0 

fdefine OK 1 


fdefine ARG(n) cipe_docall_args[n] 

fdefine ARGPTR(n) cipe_symbol_index_to_ptr(ARG(n» 
fdefine ARGDATA(n) CIPEDATA(ARGPTR(n)) 

fdefine RESULTP cipe_symbol_index_to_ptr(cipe_docall_result) 


extern int doc,nproc; 
fendif CIPEAPPL.H 
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/* codegen.h version 2.1, 7/25/88 */ 

#ifndef CODEGEN.H 
#define CODEGEN.H 

extern struct code_seg_def *cipe_init_code_segO; 

extern struct instruction *cipe_add_br_placeholder(); 

extern int compilation.error, 

#define MAX.ARGUMENTS 15 

struct forval.def { 

struct instruction *brl_loc; 
symbolnum var,expr2; 
struct instruction *expr2_loc; 
symbolnum step; 

}; 


struct ifval.def { 
symbolnum expr, 
struct instruction *brl_loc; 

}; 


struct elseval.def { 

struct instruction *br_loc,*backpatch; 

}; 


struct indexlist.def { 
unsigned int dim; 
symbolnum start,end; 
struct indexlist.def *next; 

}; 


struct exprlist.def { 
unsigned int nexprs; 
symbolnum expr, 
struct exprlist.def ♦next; 


struct arglist.def { 
unsigned int nargs; 
symbolnum arg; 
struct arglist.def *next; 


struct location.def { 
symbolnum line; 
symbolnum sample; 

}; 


struct var.name.def { 
char *name; 
char *bufpos; 
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}; 

struct attrspec_def { 
unsigned int attribute; 
char *bufpos; 

}; 

struct singleval_def { 
symbolnum symbol; 
char *bufpos; 

}; 

struct integer_def { 
int value; 
char *bufpos; 

}; 

struct float_def { 
float value; 
char *bufpos; 

}; 

struct string_def { 
char *value; 
char *bufpos; 

}; 

struct keyword_def { 
unsigned int value; 
char *bufpos; 

}; 

struct boolean_def { 
int value; 
char *buipos; 

}; 

#endif CODEGEN_H 
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/* cp_mon.h version 2.1, 7/25/88 */ 

/* 

* This file defines things used by the CP side of the CIPE 

* hypercube interface. 

*/ 


#ifndef CP_MON_H 
#define CP_MON_H 

#include "cipe.h" 

#define MAXDOC 8 

extern unsigned char whereis; /* location of data (bit map)*/ 
extern int stail; /* tail index of the symbol table */ 

extern int sindex; /* searched symbol index */ 

extern cipe_sym_name input,output; 

extern int *bufmap_send; 
extern int *bufmap_receive; 
extern int docnproc; 


extern struct cmdpacket cmd; 

#ifdef UNDEF /* no longer used */ 

/* send a command to the nodes */ 

/* CP_CMD(message,name,ackwanted); */ 

tdefine CP_CMD(m,n,a) cmd.message=(m);strcpy(cmd.name,(n));cmd.ackwanted=(a);bcastcp(&cmd,sizeof(ci 
#endif UNDEF 

#endif CP_MON_H 
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/* elt_data.h version 2.1, 7/25/88 */ 

* This file contains definitions for the data transfer functions in the 

* Hypercube node monitor 
V 


#ifndef ELT_DATA_H 
#define ELT_DATA_H 


/* definitions for "simple" data distribution types 


* i.e. values for elt_symbol.loadtype 


*/ 

#define NOT_DIST 0 

#define BCAST.DIST 1 

#define HORIZ.DIST 2 

#define VERT_DIST 3 

#define GRID_DIST 4 

#define CUSTOM_DIST 5 


/* data not in cube */ 

/* broadcast - all nodes have a copy */ 
/* row major decomposition */ 

/* column major decomposition */ 

/* grid distribution */ 

/* a custom distribution */ 


/* The following definitions used to limit amount downloaded in 
CUSTOM_DISTs at one time */ 


fdefine MAXDAT ASIZE (256*1024) /* bytes */ 


#endif ELT_DATA_H 
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/* elt_mon.h version 2 . 1 , 7 / 25/88 */ 

/* 

* This file contains definitions for the Hypercube node monitor program 
*/ 

#ifhdef ELT_MON_H 
#define ELT_MON_H 

tinclude "elt_symbol.h" 

struct cmdpacket { /* command packet used to communicate with monitor */ 

int message; 

char name[NAMESIZEj; 
int ack; 

}; 

/* values for cmdpacket.message */ 

#define READJLOADMAP 
#define READ_DATA 
tdefine WRITE_LOADMAP 
tdefine WRITEJDATA 
#define CREATE_SYMBOL 
#define DELETE_SYMBOL 
tdefine LOAD_MODULE 
tdefine EXECUTE_MODULE 
tdefine EXECUTE.BUILTIN 
tdefine REDIST_DATA 
tdefine EXIT 

/* values for cmd.ack_wanted */ 
tdefine SENDACK 1 

tdefine NOACK 0 

typedef struct { /* elt acknowledgement packet */ 

int status; /* status (OK, error, etc) */ 

int message; /* message being ack’ed */ 

} ackpacket; 

/* values for ackpacket.status */ 

tdefine ELT_OK 0 /* OK return code */ 

tdefine ELT_ERROR -1 /* error return code */ 

tdefine ELT_ACK(m,s)elt_ack.message=(m); \\ 

elt_ack.status=(s); \\ dumpelt(&eIt_ack,sizeof(ackpacket)); 
extern ackpacket elt_ack; 

tendif ELT_MON_H 


OxFFFl/* read a node symbol’s load map*/ 
0xFFF2/* read a node symbol’s data */ 
0xFFF3/* write a node symbol’s load map*/ 
0xFFF4/* write a node symbol’s data */ 
0xFFF5/* create a symbol in the nodes */ 
0xFFF6/* delete a symbol from the nodes */ 
0xFFF7/* download a node module */ 
0xFFF8/* execute the current node module */ 
0xFFF9/* execute a builtin function */ 
OxFFFA/* re-distribute data in the cube */ 
OxFFFB/* tell the node monitor to exit */ 
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/* elt_symbol.h version 2.1, 7/25/88 */ 


* This file contains the definitions for the node symbol tables used 

* for hypercube data management 
*/ 

#iftidef ELT_SYMBOL_H 
#define ELT_S YMB OL_H 

#define NAMESIZE 80 /* max length of symbol name */ 

#define MAXSYMS 100 /* max number of symbols */ 

typedef char elt_name[NAMESIZE]; /* type of symbol names */ 


struct elt_loadmap{ 
int loadtype; 
int sb; 
int nb; 
int si; 
int nl; 
int ss; 
int ns; 

}; 


/* load type if a simple type, -1 if unknown */ 
/* starting band */ 

/* number of bands */ 

/* starting line */ 

/* number of lines per band*/ 

/* starting sample */ 

/* number of samples per line */ 


struct elt_symbol{ 

unsigned char *data; /* pointer to data area */ 

elt_name name; /* symbol name */ 

int global; /* 1 if symbol is global, 0 if local */ 

int datatype; /* data type code */ 

struct elt_loadmap loadmap; /* distribution pattern */ 

}; 


/* macros for use with pointers to symbol table entries */ 


tdefine DATA(s) 

#define NAME(s) 

#define GLOBAL(s) 

#define DATATYPE(s) 
tdefine LOADMAP(s) 
#define LOADTYPE(s) 
#define SB(s) 

#define NB(s) 

#define SL(s) 

#define NL(s) 

#define SS(s) 

#define NS(s) 

#define ELEMENTSIZE(s) 
fdefine NUMELEMENTS(s) 
#define DATASIZE(s) 


((s)->data) 

((s)->name) 

((s)->global) 

((s)->datatype) 

((s)->loadmap) 

((s)->loadmap.loadtype) 

((s)->loadmap.sb) 

((s)->loadmap.nb) 

((s)->loadmap.sl) 

((s)->loadmap.nl) 

((s)->loadmap.ss) 

((s)->loadmap.ns) 

(elt_elementsize[DATATYPE(s)]) 

(NB(s)*NL(s)*NS(s)) 

(NUMELEMENTS(s)*ELEMENTSIZE(s» 


/* global array containing sizes of various types */ 
extern int elt_elementsize[]; /* defined in elt_monitor.c */ 


/* values for elt_symbol.global */ 

#define LOCALSYM 0 /* symbol is known only in cube */ 

#define GLOBALSYM 1 /* symbol is known to both elt and cp */ 
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/* definitions of data type codes 

* DO NOT CHANGE THESE WITHOUT MAKING SURE THE RESULTING CODES 

* ARE IDENTICAL ON BOTH THE CP AND ELT SIDES! 

* WHEN CHANGING THEM, BE SURE TO UPDATE THE INITIALIZATION FOR 

* elt_elementsize[] IN elt_initO TOO! 

* (CP data type codes defined in symbol.h) 

* (elt_init() defined in elt_monitor.c) 

*/ 


#ifndef SYMBOL.H 
/* included only on hypercube 
#define UNDEF.TYPE 
#define CHAR.TYPE 
#define SHORT.TYPE 
#define ENT.TYPE 
#define FLOAT.TYPE 
/* #define STRING.TYPE 
/* #define BOOL.TYPE 
/* #define KEYWORD.TYPE 
#define DOUBLE.TYPE 
#define NUM.TYPES 
#endif SYMBOL.H 


/* defined by symbol.h (on CP side only) */ 
ELT side */ 

0 /* undefined */ 

1 /* char */ 

2 /* short */ 

3 /* int */ 

4 /* float */ 

5 /* string - UNUSED IN CUBE */ 

6 /* Boolean - UNUSED IN CUBE */ 

7 f* keyword type - UNUSED IN CUBE */ 

8 /* double */ 

8 /* number of types defined */ 


typedef struct elt.symbol SYMBOL; 

#define NULLSYM ((SYMBOL *) 0) /* null symbol pointer */ 

#define NULLD ((unsigned char *) 0) /* null data pointer */ 

/* the symbol table */ 

extern SYMBOL symtab[]; /* defined in elt.symbol.c */ 


#endif ELT.S YMB OL.H 
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/* funclib.h version 2.1, 7/25/88 */ 

#ifndef FUNCLIB_H 
#define FUNCLIB_H 

#define FUNCNAMESIZE 32 

#define MAX_FUNCTIONS 5 1 1 

#define NO_FUNCTION MAX.FUNCTIONS 

typedef unsigned int functionnum; 

struct cipe_function { 
char name [FUNCNAMESIZE]; 
int args; 
int builtin; 
int result; 
int (*codeptr)0; 
struct code_seg_def *segptr, 
char *text; 
int executing; 
char *pathname; 

}; 


/* macros for use with pointers to symbol table entries */ 
#define CIPEFUNCTION(s) ((s)->name) 

#define CIPEARGS(s) ((s)->args) 

#define CIPEBUILTIN(s) ((s)->builtin) 

#define CIPERESULT(s) ((s)->result) 

#define CIPECODEPTR(s) ((s)->codeptr) 

#define CIPESEGPTR(s) ((s)->segptr) 

#define CIPETEXT(s) ((s)->text) 

#define CIPEEXECUTING(s) ((s)->executing) 

#define CIPEPATHNAME(s) ((s)->pathname) 


extern struct cipe_function *cipe_get_function_ptrO; 
extern struct cipe_function *cipe_function_index_to_ptr(); 
extern char *cipe_function_index_to_nameO; 


#endif FUNCLIB.H 
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/* image_hdr.h version 2.1, 7/25/88 */ 

tifhdef IMAGE_HDR_H 
#define IMAGE_HDR_H 

/* 

* This file contains structure and constant definitions for 

* the CIPE header. 

*/ 

#define CIPE_HEADER "CIPE" 

#define NUMB ER_LLNES "number of lines" 

#define NUMBER_SAMPLES "number of samples" 

#define NUMBER_BANDS "number of bands" 

#define CIPE_TYPE "type” 
tdefine OFFSET "offset" 

#define BYTE_STRING "byte" 
tdefine INT_STRING "int" 
tdefine FLOAT_STRING "float" 
tdefine SHORT.STRING "short" 

tdefine NUMBER_OF_BANDS_DEFAULT 1 

tdefine NUMB ER_OF_LINES_DEF AULT -1/* no default */ 

tdefine NUMBER_OF_SAMPLES_DEFAULT -1/* no default */ 

tdefine OFFSET_DEFAULT 0 

tdefine DAT A_T YPE_DEFAULT CHAR.TYPE 

struct image_header_type { 

char header_indicator[5]; 
int data_type, 

number_of_lines, 

number_of_samples, 

number_of_bands, 

offset; /* offset in bytes where data starts. */ 

/* used to skip headers. */ 
float starting_wavelength, 
ending_wavelength; 
unsigned char reserved[32]; 

struct image_header_type *next; /* for use when images */ 

/* are in a linked list. */ 


}; 

struct image_header_type *get_headerO; 
tendif IMAGE_HDR_H 
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/* menus.h version 2.1, 7/25/88 */ 

int cipe_setup(),cipe_help_function(),cipe_help_symbol(); 

int cipe_menu_read(), 
cipe_menu_write(), 
cipe_menu_assign(), 
cipe_menu_delete_symbolO. 
cipe_menu_builtin(), 
cipe_menu_applicationO, 
cipe_appl_convolveO. 
cipe_appl_frequency(), 
cipe_appl_contrast(), 
cipe_appl_size(), 
cipe_appl_tiept(), 
cipe_appl_projectO» 
cipe_appl_template_matchO. 
cipe_appl_feature_matchO. 
cipe_appl_texture_classO. 
cipe_appl_spectra_class(); 

/* display */ 

int b_aUoc(),c_aUoc0,p_alloc0.ierase0.gerase0 dstretchO,tstretch(), 

histo(),zoom0,r_cursor0,w_cursor(),draw0.rassdraw0.mssplot0.plot3d(); 

struct func_name_pair func_table[]={ 

{ cipe_setup, "setup" } , 

{ cipe_help_function,"help_function" } , 

{cipe_help_symbol,”help_symbol" } , 

{cipe_menu .assign, ”assign_data" } , 

( cipe_menu_read,"read_image" } , 

{ cipe_menu_write,"save_image" } , 

{cipe_menu_delete_symbol, "delete" } , 

{ cipe_menu_builtin,"builtin" } , 

{cipe_menu_application,"user" }, 

{ cipe_appl_convolve, "convolve" } , 

{ cipe_appl_frequency, "frequency" } , 

{ cipe_appl_contrast,"contrast" } , 

{ cipe_appl_size, "size" } , 

{ cipe_appl_tiept,"tiept" } , 

{ cipe_appl 4 >roject,"project" } , 

{ cipe_appl_template_match, "template" } , 
{cipe_appl_feature_match,"feature" } , 

{ cipe_appl_texture_class, "texture" } , 

{ cipe_appl_spectra_class,"spectra" } , 

{b_alloc,"balloc"}, 

{c_alloc,"calloc"), 

(p_alloc,"palloc"}, 

{r_cursor,"rcursor"}, 

{ w_cursor,"wcursor" } , 

{histo,"histo"} ( 

(lstretch/'lstretch"), 

(tstretch/’tstretch"}, 

{ierase,"ierase"}, 

{gerase,”gerase"}, 
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{draw,"draw"}, 

{mssplot,"msspIot"}, 

{plot3d,"plot3d"} ? 

{mssdraw,"mssdraw"}, 

{zoom,"zoom”}, 

{0,"/keep last"). 


C'"S 
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/* opcodes.h version 2.1, 7/25/88 */ 

#ifhdef OPCODES_H 
tdefine OPCODES.H 


/* instructions and program structure */ 


tdefine OPCODE.WID 6 

tdefine FUNC_IND_WID 9 

#define SYM.IND.WID 9 

#define ATTR.WID 5 

tdefine WSCMD.WID 3 

tdefine STATUS.WID 3 

tdefine EXECPART.WID 3 

tdefine BOOL.WID 1 

tdefine SCOPE.WID 1 


tdefine MENU_MODE_WID 1 


struct instruction { 
unsigned iru opcode 
union { 
struct { 

symbolnum lhs 
symbolnum rhs 
symbolnum result 
} arith,rel,bool; 
struct { 

symbolnum src 
symbolnum dest 
} assign; 
struct { 

symbolnum arg 
symbolnum result 
struct indexlist.def *indices; 
} index; 
struct { 

functionnum func 
struct exprlist.def *args; 
symbolnum result 
} call; 
struct { 

symbolnum loc 
symbolnum exprl 
symbolnum expr2 
symbolnum step 
} br.brz.brfor, 
struct { 

unsigned int attr 
symbolnum value 
} set; 
struct { 

unsigned int command 
symbolnum ws 
} wscmd; 


: OPCODE_WID; 


SYM_IND_WID 

SYMJND.WID 

SYM_IND_WID 


: SYM_IND_WID; 
: SYMJND.WID; 


: SYM_IND_WID; 
: SYM_IND_WID; 


: FUNC JND.WID; 
: SYM.IND.WID; 


SYM_IND_WID; 

SYMJND.WID; 

SYM_IND_WID; 

SYM_IND_WID; 


: ATTR.WID; 

: SYMJND.WID; 


: WSCMD. WID; 

; SYMJND.WID; 
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struct { 

char *cmd; 

} shellcmd; 
struct { 

char *name; 

struct code_seg_def *codeseg; 
struct arglist_def *args; 
unsigned int result; 
char *text; 

unsigned int scope : SCOPE_WID; 

} define; 
struct { 

struct exprlist_def *exprs; 

} print; 
struct { 

functionnum func : FUNC_IND_WID; 

} show; 
struct { 

symbolnum symbol : SYM_END_WID; 

symbolnum filename : SYM_IND_WID; 

} read, write; 
struct { 

symbolnum image : SYM_IND_WID; 

struct location_def location; 

} display; 
struct { 

unsigned int menumode : MENU_MODE_WID; 

} menu; 

} fields; 

}; 

extern struct code_seg_def *code_seg; 
extern int num_code_segs; 
extern struct instruction *curr_op; 

#define NOP_CODE 0 /* NOP - no arguments*/ 

#define LT_CODE 1 /* RELationals - argl, arg2, result*/ 

fdefine LTE.CODE 2 

#define EQ_CODE 3 

#define NE_CODE 4 

#define GTE_CODE 5 

fdefine GT_CODE 6 

fdefine AND_CODE 7 /* BOOLeans - argl, arg2, result*/ 

fdefine OR_CODE 8 

fdefine B IT AND_CODE 9 

fdefine BITOR.CODE 10 

fdefine BITXOR_CODE 11 

fdefine PLUS_CODE 12 /* arithmetics - argl, arg2, result*/ 

fdefine MINUS.CODE 13 

fdefine MULT_CODE 14 

fdefine DIV_CODE 15 

fdefine GETS_CODE 16 /* GETS - source, destination*/ 

fdefine NOT_CODE 17 /* lARGument (unary) ops - arg, result*/ 

fdefine BITNOT_CODE 18 
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#define NEGATE_CODE 19 

tdeflne INDEX_CODE 20 

#define CALL_CODE 21 

#define BR_CODE 22 

#define BRZ_CODE 23 

tdeflne BRFOR_CODE 24 

tdeflne SET_CODE 25 

#define WSCMD_CODE 26 

#define BANG_CODE 27 

tdeflne QUIT_CODE 28 

#define STATUS_CODE 29 

#define DEFINE_CODE 30 

#define PRINT_CODE 31 

#define SHOW_CODE 32 

tdeflne FUNCTIONS.CODE 33 
#define SYMBOLS_CODE 34 

#define TRACES.CODE 35 

#define READ.CODE 36 

tdeflne WRITE.CODE 37 

tdeflne DISPLAY_CODE 38 

tdeflne MENU.CODE 39 

tdeflne HELP_CODE 40 


/* SPECIAL - argl, result, indices*/ 
/* func, arglist*/ 

/* location*/ 

/* location, expr*/ 

/* location, exprl, step, expr2*/ 
/* SYSCMD - anr, value*/ 

/* workspace name*/ 

/* unix command*/ 

/* no arguments*/ 

/* display current status*/ 

/* name, code seg ptr, arg list*/ 

/* expr*/ 

/* function index*/ 

/* no arguments*/ 

/* no arguments*/ 

/* no arguments*/ 

/* expressions, filename*/ 

/* expressions, filename*/ 

/* symbol index*/ 

/* no arguments*/ 

/* no arguments*/ 


tdeflne ISNOP(op) (op == NOP_CODE) 


tdeflne ISREL(op) (op >= LT.CODE && op <= GT_CODE) 
tdeflne ISBOOL(op) (op >= AND.CODE && op <= BITXOR_CODE) 
tdeflne IS2ARG(op) (op >= LT.CODE && op <= DIV.CODE) 


tdeflne ISGETS(op) (op == GETS.CODE) 

tdeflne ISlARG(op) (op == NOT_CODE II op == BITNOT_CODE II op = NEGATE_CODE) 


tdeflne ISCALL(op) (op == CALL.CODE) 
tdeflne ISINDEX(op) (op == INDEX.CODE) 

tdeflne ISBRANCH(op) (op == BR.CODE II op — BRZ_CODE II op == BRFOR.CODE) 
tdeflne ISSPEaAL(op) (ISCALL(op) || ISINDEX(op) II ISBRANCH(op)) 


tdeflne ISSET(op) (op = SET_CODE) 

tdeflne ISWSCMD(op) (op == WSCMD.CODE) 

tdeflne ISBANG(op) (op = BANG_CODE) 

tdeflne ISQUIT(op) (op = QUIT.CODE) 

tdeflne ISSYMBOLS(op) (op == SYMBOLS.CODE) 

tdeflne ISFUNCTIONS(op) (op == FUNCTIONS.CODE) 

tdeflne ISTRACES(op) (op == TRACES_CODE) 

tdeflne ISSHOW(op) (op == SHOW.CODE) 

tdeflne ISDEFINE(op) (op == DEFINE_CODE) 

tdeflne ISPRINT(op) (op == PRINT_CODE) 

tdeflne ISREAD(op) (op == READ_CODE) 

tdeflne ISWRITE(op) (op == WRITE_CODE) 

tdeflne ISDISPLAY(op) (op == DISPLAY.CODE) 

tdeflne ISMENU(op) (op == MENU_CODE) 

tdeflne ISHELP(op) (op == HELP_CODE) 

tdeflne ISSYSCMD(op) (op >= SET_CODE && op <= HELP_CODE) 
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struct builtin_def { 
char *name; 
int (*type_check)(); 
int (*exec_code)(); 


extern int cipe_lt_builtin(),cipeJte_builtinO,cipe_eq_builtinO, 
cipe_ne_builtin(),cipe_gte_builtinO,cipe_gt_builtin(); 
extern int cipe_and_builtinO,cipe_or_builtinO,cipe_bitand_builtinO, 
cipe_bitor_builtin0.cipe_bitxor_buiItin(); 
extern int cipe_plus_builtinO,cipe_minus_builtinO,cipe_rault_builtinO, 
cipe_div_builtinO; 

extern int cipe_int_floatO,cipe_int_onlyO; 

extern struct builtin_def builtins[]; 

/* workspace commands */ 

#define LOADWS 0 

#define SAVEWS 1 

#define EDITWS 2 

extern char *wscmds[]; 


#endif OPCODES_H 
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/* symbol.h version 2.1, 7/25/88 */ 

#ifndef SYMBOL_H 
#define SYMBOL_H 

#define SYMBOL_NOT_FOUND 0x00 
#define SYMBOL_IN_CIPE 0x01 
#define SYMBOL_IN_CUBE 0x02 
#define SYMBOL_IN_FILE 0x04 
#define CIPENAMES1ZE 80 

#define MAX_SYMBOLS 511 
#define NO_SYMBOL MAX.SYMBOLS 

struct loadmap { 
int Ioadtype; 
int sb; 
int nb; 
int si; 
int nl; 
int ss; 
int ns; 

}; 


struct cipe_symbol { 
unsigned char *data; 
char name[CIPENAMESIZE]; 
char file[CIPENAMESIZE]; 
unsigned int ndim; 
unsigned int sb; 
unsigned int nb: 
unsigned int si; 
unsigned int nl; 
unsigned int ss; 
unsigned int ns; 
unsigned int datatype; 
unsigned int Ioadtype; 
struct loadmap *cubeload; 

}; 


extern int cipe_size[]; 


/* macros for use with pointers to symbol table entries */ 
tdefine CIPEDATA(s) ((s)->data) 

#define CIPENAME(s) ((s)->name) 


#define CIPEFILE(s) 
#define CIPENDIM(s) 
#define CIPESB(s) 
#define CDPENB(s) 
#define CIPESL(s) 
#define CIPENL(s) 
#define CIPESS(s) 
#define CIPENS(s) 


((s)->file) 

((s)->ndim) 

((s)->sb) 

((s)->nb) 

((s)->sl) 

((s)->nl) 

((s)->ss) 

((s)->ns) 


#define CIPEDATATYPE(s) ((s)->datatype) 
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#define CIPELOADTYPE(s) ((s)->loadtype) 

#define CIPELOADMAP(s) ((s)->cubeload) 

#define CIPEELEMENTSIZE(s) cipe_size[CIPEDATATYPE(s)] 

#define CIPENUMELEMENTS(s) CIPENL(s)*CIPENS(s)*CIPENB(s) 

#define CIPEDATASIZE(s) CIPENUMELEMENTS(s) *CIPEELEMENTSIZE(s) 

/* function types */ 

extern struct cipe_symbol *cipe_get_symbol_ptrO; 
extern struct cipc_symboI *cipe_symbol_index_to_ptr(); 
extern char *cipe_symbol_index_to_name(); 


typedef unsigned int symbolnum; 

tdefine UNDEF_TYPE 0 
#define CHAR.TYPE 1 
#define SHORT_TYPE 2 
#define INT_TYPE 3 
#define FLOAT_TYPE 4 
#define DOUB LE_TYPE 5 

#define BOOL.TYPE 6 
#define STRING_TYPE 7 

#define KE Y W ORD_TYPE 8 

#define NUM_TYPES 9 


#endif SYMBOL_H 



TECHNICAL REPORT STANDARD TITLE PAGE 


1 . Report No . 


88-32 


2. Government Accession No. 3. Recipient's Catalog No. 


4. Title and Subtitle 

CONCURRENT IMAGE PROCESSING EXECUTIVE (CIPE) 


5. Report Date 

I Q- 1-8 .9 

6. Performing Organization Code 


7. Author (s) 

Meemong Lee 

9. Performing Organization Name and Address 

JET PROPULSION LABORATORY 
California Institute of Technology 
4800 Oak Grove Drive 
Pasadena, California 91109 

12. Sponsoring Agency Name and Address 

NATIONAL AERONAUTICS AND SPACE ADMINISTRATION 
Washington, D.C. 20546 


8. Performing Organization Report No. I 


10. Work Unit No. 


11. Contract or Grant No. 

NAS7-918 

13. Type of Report and Period Covered 

JPL Publication 


14. S 




15. Supplementary Notes 


16. Abstract __ 

This report describes the design and implementation of a Concurrent Image 
Processing Executive (CIPE) , which is intended to become the support system software 
for a prototype high performance science analysis workstation. The target machine for 
this software is a JPL/Caltech Mark Illfp Hypercube hosted by either a MASSC0MP 5600 
or a Sun-3, Sun-4 workstation; however, the design will accommodate other concurrent 
machines of similar architecture, i.e., local memory, multiple- instruction-multiple- 
data (MIMD) machines. The CIPE system provides both a multimode user interface and an 
applications programmer interface, and has been designed around four loosely coupled 
modules; (1) user interface, (2) host-resident executive, (3) hy.percube-resident 
executive, and (4) application functions. The loose coupling between modules allows 
modification of a particular module without significantly affecting the other modules 
in the system. In order to enhance hypercube memory utilization and to allow 
expansion of image processing capabilities, a specialized program management method, 
.incremental loading, was devised. To minimize data transfer between host and hypercube 
a data management method which distributes, redistributes, and tracks data set 
information was implemented. The data management also allows data sharing among 
application programs. The GIBE ‘software architecture provides a flexible environment 
for scientific analysis of complex remote sensing image data, such as imaging 
spectrometry, utilizing state-of-the-art concurrent computation capabilities. 


17. Key Words (Selected by Author(s)) 

Geosciences and Oceanography (General) , 
Computer Programming and Software, 

Space Sciences (General) 


18. Distribution Statement 


Unclassified — Unlimited 


19. Security Classif. (of this report) 20. Security Classif. (of this page) 21. No. of Pages 22. Price 

UNCLASSIFIED UNCLASSIFIED 200 







